@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
@@ -0,0 +1,155 @@
1
+ import type { BlockId } from "../blocks/index.js";
2
+ import type { BranchNode, LeafNode } from "./nodes.js";
3
+ import { jsonEncodedBytes } from "../network/transaction-size.js";
4
+
5
+ // The arithmetic behind a node's size limit: how a node's items divide into nodes once they no
6
+ // longer fit one, by count or by bytes. Every function here is pure, so a replayed or retried action
7
+ // divides a node identically; the tree (`btree.ts`) applies the division it is handed. A node's JSON
8
+ // is its header and empty arrays (a fixed part per node) plus each item's JSON and the commas between
9
+ // them, so one serialization per item answers both whether a node fits and where to divide it.
10
+
11
+ /** The byte rule a node's items are divided under: the target, and the bytes a node holding items
12
+ * `[from, to)` encodes to. */
13
+ export type ItemBytes = { target: number; between(from: number, to: number): number };
14
+
15
+ /** The byte rule for a leaf that would hold `entries`: its fixed part plus the entries and the
16
+ * commas between them. */
17
+ export function leafItemBytes(leaf: LeafNode<unknown>, entries: readonly unknown[], target: number): ItemBytes {
18
+ const before = prefixSums(itemBytes(entries));
19
+ const base = emptyLeafBytes(leaf);
20
+ return {
21
+ target,
22
+ between: (from, to) => base + before[to]! - before[from]! + Math.max(0, to - from - 1),
23
+ };
24
+ }
25
+
26
+ /** The byte rule for a branch that would hold children `nodes` under the keys `partitions`. A run of
27
+ * children `[from, to)` carries the keys between them; the key before `from` is promoted to the
28
+ * parent and counts on neither side. */
29
+ export function branchItemBytes(branch: BranchNode<unknown>, partitions: readonly unknown[], nodes: readonly BlockId[], target: number): ItemBytes {
30
+ const ids = prefixSums(itemBytes(nodes));
31
+ const keys = prefixSums(itemBytes(partitions));
32
+ const base = emptyBranchBytes(branch);
33
+ return {
34
+ target,
35
+ between: (from, to) => base + ids[to]! - ids[from]! + keys[to - 1]! - keys[from]!
36
+ + Math.max(0, to - from - 1) + Math.max(0, to - from - 2),
37
+ };
38
+ }
39
+
40
+ /** What a leaf encodes to with no entries: the part of its size the entries do not account for. */
41
+ export function emptyLeafBytes(leaf: LeafNode<unknown>): number {
42
+ return jsonEncodedBytes({ header: leaf.header, entries: [] });
43
+ }
44
+
45
+ /** What a branch encodes to with no children: the part of its size the keys and ids do not account for. */
46
+ export function emptyBranchBytes(branch: BranchNode<unknown>): number {
47
+ return jsonEncodedBytes({ header: branch.header, partitions: [], nodes: [] });
48
+ }
49
+
50
+ /** The JSON size of each item, by the measure block limits are judged with. */
51
+ function itemBytes(items: readonly unknown[]): number[] {
52
+ return items.map(item => jsonEncodedBytes(item));
53
+ }
54
+
55
+ /** Running totals: `sums[i]` is the bytes of the first `i` items, so any run of items is one subtraction. */
56
+ function prefixSums(sizes: readonly number[]): number[] {
57
+ const sums = [0];
58
+ for (const size of sizes) {
59
+ sums.push(sums[sums.length - 1]! + size);
60
+ }
61
+ return sums;
62
+ }
63
+
64
+ /**
65
+ * How `count` items of one node divide into nodes when they no longer fit one, as run boundaries —
66
+ * run `i` is the items `[runs[i], runs[i + 1])`, the first boundary 0 and the last `count` — or
67
+ * `undefined` when they fit. A run fits when it holds at most `capacity` items and either no more
68
+ * than `always` items (one entry, or two children: the least a node of its kind holds, so a node over
69
+ * the byte target holds no more than that) or, under the byte rule, no more than the target's bytes.
70
+ *
71
+ * - Over the count alone: two runs at the midpoint ({@link countSplit}), the division the tree has
72
+ * always made, kept as it was so a tree of small entries writes the transforms it always did.
73
+ * - Over the bytes: the fewest fitting runs ({@link fewestRuns}), so an entry larger than the target
74
+ * is left alone in a node of its own and a node that outgrew the target before this rule existed is
75
+ * brought within it in one write; where two runs suffice, the two whose larger is smallest
76
+ * ({@link balancedSplit}).
77
+ */
78
+ export function divideItems(count: number, capacity: number, at: number, always: number, bytes?: ItemBytes): number[] | undefined {
79
+ const fits = (from: number, to: number) => to - from <= capacity
80
+ && (bytes === undefined || to - from <= always || bytes.between(from, to) <= bytes.target);
81
+ if (fits(0, count)) {
82
+ return undefined;
83
+ }
84
+ if (bytes === undefined || count <= always || bytes.between(0, count) <= bytes.target) {
85
+ return [0, countSplit(count, at), count]; // the count is the only reason
86
+ }
87
+ const runs = fewestRuns(count, always, fits);
88
+ if (runs.length === 3) {
89
+ runs[1] = balancedSplit(count, always, fits, bytes.between, runs[1]!);
90
+ }
91
+ return runs;
92
+ }
93
+
94
+ /** Which run of `runs` (see {@link divideItems}) item `index` falls in. */
95
+ export function runOf(runs: readonly number[], index: number): number {
96
+ let run = 0;
97
+ while (index >= runs[run + 1]!) {
98
+ ++run;
99
+ }
100
+ return run;
101
+ }
102
+
103
+ /** Where the count rule divides `count` items: at the midpoint, the odd item going to the half the
104
+ * edit at `at` lands in. */
105
+ function countSplit(count: number, at: number): number {
106
+ const mid = count >>> 1;
107
+ return mid + (at < mid ? 1 : 0);
108
+ }
109
+
110
+ /** The fewest runs that each fit, packing from the left: as many items into a run as fit, then the
111
+ * next run. A final run of a single item takes one more from the run before it when that run can
112
+ * spare one (it keeps more than `always`) and the pair fits — so a branch is not left routing to one
113
+ * child when its neighbour could have given it another.
114
+ *
115
+ * NOTE: three children whose two keys each pass half the target still leave a one-child branch (the
116
+ * run before it holds only `always`); the tree routes through it, and a delete merges it away. Only
117
+ * a key over half the target gets there, which no key the SQL layer frames does; if one ever does,
118
+ * let a run take an item past the target before leaving one alone. */
119
+ function fewestRuns(count: number, always: number, fits: (from: number, to: number) => boolean): number[] {
120
+ const runs = [0];
121
+ for (let from = 0; from < count;) {
122
+ let to = from + 1;
123
+ while (to < count && fits(from, to + 1)) {
124
+ ++to;
125
+ }
126
+ runs.push(to);
127
+ from = to;
128
+ }
129
+ const last = runs.length - 1;
130
+ if (last >= 2 && runs[last]! - runs[last - 1]! === 1 && runs[last - 1]! - runs[last - 2]! > always && fits(runs[last - 1]! - 1, count)) {
131
+ runs[last - 1] = runs[last - 1]! - 1;
132
+ }
133
+ return runs;
134
+ }
135
+
136
+ /** Where to divide `count` items into two runs that both fit so that the larger run's bytes are as
137
+ * small as possible. Each run keeps at least `always` items when the count allows, so a branch is
138
+ * not divided down to one child for the sake of balance. `fallback` is a division already known to
139
+ * fit, returned when no candidate does. */
140
+ function balancedSplit(count: number, always: number, fits: (from: number, to: number) => boolean, between: (from: number, to: number) => number, fallback: number): number {
141
+ const least = count >= 2 * always ? always : 1;
142
+ let best = fallback;
143
+ let bestLarger = Infinity;
144
+ for (let m = least; m <= count - least; ++m) {
145
+ if (!fits(0, m) || !fits(m, count)) {
146
+ continue;
147
+ }
148
+ const larger = Math.max(between(0, m), between(m, count));
149
+ if (larger < bestLarger) {
150
+ bestLarger = larger;
151
+ best = m;
152
+ }
153
+ }
154
+ return best;
155
+ }
@@ -3,6 +3,7 @@ import type { BlockStore, BlockId, IBlock } from "../index.js";
3
3
  import { ChainDataBlockType, ChainHeaderBlockType, entries$, headId$, nextId$, priorId$, tailId$ } from "./chain-nodes.js";
4
4
  import type { ChainDataNode, ChainHeaderNode } from "./chain-nodes.js";
5
5
  import { apply } from "../blocks/index.js";
6
+ import { jsonEncodedBytes } from "../network/transaction-size.js";
6
7
 
7
8
  export const EntriesPerBlock = 32;
8
9
 
@@ -20,6 +21,17 @@ export type ChainInitOptions<TEntry> = {
20
21
  createDataBlock?: () => ChainNodeInit<ChainDataNode<TEntry>>;
21
22
  createHeaderBlock?: (id?: BlockId) => ChainNodeInit<ChainHeaderNode>;
22
23
  newBlock?: (newTail: ChainDataNode<TEntry>, oldTail: ChainDataNode<TEntry> | undefined) => Promise<void>;
24
+ /**
25
+ * When set, a data block that already holds an entry also starts a new block once the next entry
26
+ * would take its encoded size (`jsonEncodedBytes`) past this many bytes — besides the
27
+ * {@link EntriesPerBlock} count, which always applies. A block holding no entry always takes the
28
+ * next one, so an entry larger than this sits alone in its own block. Absent, blocks roll over by
29
+ * count alone. The log sets it to `BLOCK_TARGET_BYTES`.
30
+ *
31
+ * The decision is a pure function of the tail block's content and the entries being added, so a
32
+ * retried append at the same revision splits identically.
33
+ */
34
+ blockTargetBytes?: number;
23
35
  }
24
36
 
25
37
  export type ChainCreateOptions<TEntry> = ChainInitOptions<TEntry> & {
@@ -109,19 +121,21 @@ export class Chain<TEntry> {
109
121
  const trx = new Atomic(this.store);
110
122
 
111
123
  // Attempt to fit in current block
112
- const copied = entries.slice(0, EntriesPerBlock - tail.entries.length);
113
- if (copied.length > 0) {
114
- apply(trx, tail, [entries$, tail.entries.length, 0, copied]);
115
- entries = entries.slice(copied.length);
124
+ let next = this.takenBy(tail, entries, 0);
125
+ if (next > 0) {
126
+ apply(trx, tail, [entries$, tail.entries.length, 0, entries.slice(0, next)]);
116
127
  }
117
128
 
118
- while (entries.length > 0) {
129
+ while (next < entries.length) {
119
130
  const newTail = {
120
131
  ...(this.options?.createDataBlock?.() ?? { header: this.store.createBlockHeader(ChainDataBlockType) }),
121
- entries: entries.splice(0, Math.min(EntriesPerBlock, entries.length)),
132
+ entries: [] as TEntry[],
122
133
  priorId: tail.header.id,
123
134
  nextId: undefined,
124
135
  } as ChainDataNode<TEntry>;
136
+ const taken = this.takenBy(newTail, entries, next);
137
+ newTail.entries = entries.slice(next, next + taken);
138
+ next += taken;
125
139
  // Predecessor is the running `tail` (immediately preceding block), NOT the original
126
140
  // `oldTail`: across a multi-block append each new block links to the one before it.
127
141
  await this.options?.newBlock?.(newTail, tail);
@@ -139,6 +153,41 @@ export class Chain<TEntry> {
139
153
  return { headerBlock, block: tail, index: tail.entries.length - 1 };
140
154
  }
141
155
 
156
+ /**
157
+ * How many of `entries`, from `start`, `block` takes before it is full: up to
158
+ * {@link EntriesPerBlock} entries, and — when the chain has a byte target — no further entry once
159
+ * it holds one and the next would take it past the target. A block holding no entry always takes
160
+ * the first, so this is at least one for an empty block with entries left to place.
161
+ *
162
+ * The measure is the block's JSON as it stands, not counting what the `newBlock` hook adds to a
163
+ * new block afterwards (the log's `priorHash`) nor what a caller writes into an entry after the add
164
+ * (the log's `blockIds`) — both small against the gap between the target and the most a block may
165
+ * hold.
166
+ */
167
+ private takenBy(block: ChainDataNode<TEntry>, entries: readonly TEntry[], start: number): number {
168
+ const room = Math.max(0, Math.min(EntriesPerBlock - block.entries.length, entries.length - start));
169
+ const target = this.options?.blockTargetBytes;
170
+ if (target === undefined || room === 0) {
171
+ return room;
172
+ }
173
+ // NOTE: serializes the whole tail block once per append, the same order of cost as the commit
174
+ // path's digest of every touched block. If appends to large logs ever show this in a profile,
175
+ // keep a running byte count for the tail instead of re-measuring it.
176
+ let bytes = jsonEncodedBytes(block);
177
+ let held = block.entries.length;
178
+ let taken = 0;
179
+ for (; taken < room; ++taken) {
180
+ // Each entry after the first adds its own JSON plus the separating comma.
181
+ const grown = bytes + jsonEncodedBytes(entries[start + taken]) + (held > 0 ? 1 : 0);
182
+ if (held > 0 && grown > target) {
183
+ break;
184
+ }
185
+ bytes = grown;
186
+ ++held;
187
+ }
188
+ return taken;
189
+ }
190
+
142
191
  /** Updates the entry at the given path. */
143
192
  updateAt(path: ChainPath<TEntry>, entry: TEntry) {
144
193
  if (!pathValid(path)) {
@@ -1,5 +1,6 @@
1
1
  import type { RepoMessage } from "../network/repo-protocol.js";
2
2
  import type { CommitResult, PendResult } from "../network/struct.js";
3
+ import type { ValidityRejection } from "../transaction/transaction.js";
3
4
 
4
5
  /**
5
6
  * One member's vote on a cluster transaction, in either the promise or the commit map.
@@ -11,6 +12,10 @@ import type { CommitResult, PendResult } from "../network/struct.js";
11
12
  */
12
13
  export type Signature =
13
14
  | { type: 'approve'; signature: string }
15
+ /**
16
+ * A plain reject, or an **expiry vote**. Never a validity vote: `validity` belongs to the other
17
+ * reject arm, so one vote cannot claim both a clock disagreement and a validity judgement.
18
+ */
14
19
  | {
15
20
  type: 'reject';
16
21
  signature: string;
@@ -23,6 +28,25 @@ export type Signature =
23
28
  * Still a `reject` in every count — the record really is dead for this member.
24
29
  */
25
30
  expiredAt?: number;
31
+ validity?: never;
32
+ }
33
+ /**
34
+ * A **validity vote**: the member re-checked the transaction and judged it wrong in a way that holds
35
+ * on every retry and at every honest validator (see {@link ValidityRejection} for which refusals
36
+ * qualify). `validity.computedHash` is the operations hash the member computed, when re-execution got
37
+ * that far. Signed like `expiredAt`, so a coordinator can tell "refused for good" from "try again"
38
+ * without reading `rejectReason`.
39
+ *
40
+ * Absent means "not known to be a validity judgement" — a stale revision, a reservation, a refusal the
41
+ * member could not judge, or a member on a build that predates the field — so a reader must never
42
+ * treat an unmarked reject as final. Still a `reject` in every count.
43
+ */
44
+ | {
45
+ type: 'reject';
46
+ signature: string;
47
+ rejectReason?: string;
48
+ validity: ValidityRejection;
49
+ expiredAt?: never;
26
50
  }
27
51
  /**
28
52
  * This member refuses the transaction *for now*: it holds a conflicting transaction that won
@@ -68,13 +92,21 @@ export type ClusterVote = Unsigned<Signature>;
68
92
  * held's `heldBy`, nothing for an approve. Folding the extra in is what makes it integrity-protected in
69
93
  * transit rather than free-floating prose.
70
94
  *
71
- * One variant carries two fields: an expiry vote, a `reject` with {@link Signature} `expiredAt`. It is
72
- * encoded `<hash>:reject-expired:<json>`, where `<json>` is `JSON.stringify([expiredAt, rejectReason ??
73
- * null])`. Two properties make that unambiguous: the tag differs from every other vote's at the
74
- * character after `reject` (a hash is base64url, so the first `:` always ends it), and a JSON array
75
- * cannot be read as a different pair of values. A reason that itself contains `:` — `"x:5"` — can
76
- * therefore never verify as reason `"x"` with `expiredAt: 5`, and a string smuggled into `expiredAt`
77
- * changes the bytes. Every vote without `expiredAt` encodes exactly as before the field existed.
95
+ * Two reject variants carry two fields each, and each has its own tag:
96
+ * - an expiry vote, a `reject` with {@link Signature} `expiredAt`, is encoded
97
+ * `<hash>:reject-expired:<json>`, where `<json>` is `JSON.stringify([expiredAt, rejectReason ?? null])`;
98
+ * - a validity vote, a `reject` with {@link Signature} `validity`, is encoded
99
+ * `<hash>:reject-invalid:<json>`, where `<json>` is `JSON.stringify([computedHash ?? null,
100
+ * rejectReason ?? null])`.
101
+ *
102
+ * Two properties make that unambiguous. The tag is decided character by character after the hash (a
103
+ * hash is base64url, so the first `:` always ends it): a plain reject continues `reject` with `:` or
104
+ * nothing, the two marked ones with `-`, and those two differ at the next character (`e` and `i`); every
105
+ * other vote's tag differs from all three at its first character. And a JSON array cannot be read as a
106
+ * different pair of values. A reason that itself contains `:` — `"x:5"` — can therefore never verify as
107
+ * reason `"x"` with `expiredAt: 5`, a string smuggled into `expiredAt` changes the bytes, and adding,
108
+ * removing or altering a vote's `validity` changes them too. The type keeps the two marked forms apart
109
+ * (no vote carries both). Every vote with neither field encodes exactly as before either existed.
78
110
  *
79
111
  * Producers and verifiers must both build the preimage here. It lives beside {@link Signature}
80
112
  * rather than in either consumer because a second copy that forgets a variant does not fail loudly:
@@ -98,6 +130,9 @@ export function clusterVoteVerificationPayload(hash: string, signature: Signatur
98
130
  function voteTagAndExtra(vote: ClusterVote): string {
99
131
  switch (vote.type) {
100
132
  case 'reject':
133
+ if (vote.validity !== undefined) {
134
+ return 'reject-invalid:' + JSON.stringify([vote.validity.computedHash ?? null, vote.rejectReason ?? null]);
135
+ }
101
136
  return vote.expiredAt === undefined
102
137
  ? withExtra('reject', vote.rejectReason)
103
138
  : 'reject-expired:' + JSON.stringify([vote.expiredAt, vote.rejectReason ?? null]);
@@ -15,6 +15,40 @@ export type Action<T> = {
15
15
 
16
16
  export type ActionHandler<T, TResult = void> = (action: Action<T>, store: BlockStore<IBlock>) => Promise<TResult>;
17
17
 
18
+ /**
19
+ * What one run of a collection's action handler accepted as ALREADY APPLIED — the answer a handler may
20
+ * give (`CollectionInitOptions.modules` types every handler as returning one or nothing), summed by
21
+ * `Collection.stageInto` over the actions it stages and recorded on the sealed segment they belong to
22
+ * (`SealedSegment.applied`). Today only the tree's `replace` handler counts anything: for each element
23
+ * whose guard is one of the three already-applied kinds (`TreeAlreadyAppliedGuard` in
24
+ * `packages/db-core/src/collections/tree/struct.ts`), `alreadyApplied` when the element was skipped
25
+ * because a rival had made exactly its change, `applied` when it was written or deleted; and `applied`
26
+ * for each element written under `absent` or `unchanged`, the exact-key base kinds that write whenever
27
+ * they do not refuse and that the SQL layer stages on every main-table element, so a plain insert
28
+ * beside an already-applied update keeps the entry `applied`. Elements with no guard, or with
29
+ * `keepExisting` (a skip that says nothing about equality) or `absentRange` — the shapes an index
30
+ * tree's entries take — are not counted, so {@link ZeroTally} is the tally of an action with no counted
31
+ * element, and of a handler that returns nothing (`Diary`'s).
32
+ *
33
+ * The offline queue sums an entry's tallies over every collection it wrote and reports
34
+ * `effect: 'already-applied'` on its `committed` status exactly when `alreadyApplied > 0` and
35
+ * `applied === 0`: every element that could have been already applied was, and at least one was
36
+ * (docs/offline-sync.md §Guards that make idempotent writes assured). "All, not any", because a host
37
+ * reading `already-applied` as "none of my guarded changes landed" must be right.
38
+ */
39
+ export type AlreadyAppliedTally = {
40
+ readonly alreadyApplied: number;
41
+ readonly applied: number;
42
+ };
43
+
44
+ /** The tally of a handler that counted nothing. */
45
+ export const ZeroTally: AlreadyAppliedTally = Object.freeze({ alreadyApplied: 0, applied: 0 });
46
+
47
+ /** `a + b`, field by field. */
48
+ export function addTallies(a: AlreadyAppliedTally, b: AlreadyAppliedTally): AlreadyAppliedTally {
49
+ return { alreadyApplied: a.alreadyApplied + b.alreadyApplied, applied: a.applied + b.applied };
50
+ }
51
+
18
52
  export type ActionRev = {
19
53
  actionId: ActionId;
20
54
  rev: number;