@jam-overture/loom 0.1.0 → 0.2.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 (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -0,0 +1,327 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { audienceScopeRead, comparedAudiencesOf, crossesAudiences, } from "./audiences.js";
3
+ import { readingProgressOf } from "./progress.js";
4
+ export const CHANGE_SILENCES = everyMemberOf()([
5
+ "different-trees",
6
+ "different-audiences",
7
+ "audiences-mixed",
8
+ "nothing-measured",
9
+ ]);
10
+ /** One line per silence, for a surface putting the comparison in front of a person. */
11
+ export const describeChangeSilence = (silence) => {
12
+ switch (silence) {
13
+ case "different-trees":
14
+ return "the two readings are of different pages";
15
+ case "different-audiences":
16
+ return "the two readings are of different audiences, and so of different readers";
17
+ case "audiences-mixed":
18
+ return "one window holds two forms of the page and says which readers neither";
19
+ case "nothing-measured":
20
+ return "one of the two windows held no page views";
21
+ }
22
+ };
23
+ export const PAIR_FATES = everyMemberOf()([
24
+ "absent",
25
+ "moved",
26
+ "reordered",
27
+ "separated",
28
+ "unanchorable",
29
+ "unreached",
30
+ ]);
31
+ /** One line per fate, for a surface putting the comparison in front of a person. */
32
+ export const describePairFate = (fate) => {
33
+ switch (fate) {
34
+ case "absent":
35
+ return "one of the two parts is not in the other revision";
36
+ case "moved":
37
+ return "the two parts are no longer children of the same part";
38
+ case "reordered":
39
+ return "the two parts are now the other way round";
40
+ case "separated":
41
+ return "something now sits between the two parts";
42
+ case "unanchorable":
43
+ return "one of the two parts reported nothing that could anchor a stop";
44
+ case "unreached":
45
+ return "nobody reached the first of the two parts";
46
+ }
47
+ };
48
+ const NO_PARTS = Object.freeze({
49
+ shared: 0,
50
+ added: Object.freeze([]),
51
+ removed: Object.freeze([]),
52
+ moved: Object.freeze([]),
53
+ reworded: Object.freeze([]),
54
+ unreadable: 0,
55
+ });
56
+ const keyOf = (after, before) => `${after}\u0000${before}`;
57
+ const sideOf = (after, before) => {
58
+ const lost = Math.max(after.reached - before.reached, 0);
59
+ return {
60
+ reached: after.reached,
61
+ lost,
62
+ share: after.reached === 0 ? 0 : lost / after.reached,
63
+ };
64
+ };
65
+ /**
66
+ * Every pair of consecutive anchorable steps of every run, in reading order.
67
+ *
68
+ * Rebuilt from the steps rather than read off {@link ReadingProgress.stops},
69
+ * because a pair nobody stopped at is a measurement this module needs and a fall
70
+ * is the only thing progress keeps. A pair whose share went to zero is the best
71
+ * outcome a change can have, and reading only the falls would lose exactly that.
72
+ *
73
+ * One pass per run, carrying the previous anchorable step rather than searching
74
+ * backwards, which is how `progress.ts` stays linear and why the ledger is not
75
+ * quadratic any more.
76
+ */
77
+ const adjacenciesOf = (progress) => {
78
+ const pairs = [];
79
+ for (const run of progress.runs) {
80
+ let previous;
81
+ for (const step of run.steps) {
82
+ if (!step.anchors)
83
+ continue;
84
+ if (previous !== undefined) {
85
+ pairs.push({
86
+ after: previous.nodeId,
87
+ before: step.nodeId,
88
+ parentId: run.parentId,
89
+ side: sideOf(previous, step),
90
+ });
91
+ }
92
+ previous = step;
93
+ }
94
+ }
95
+ return pairs;
96
+ };
97
+ const placementsOf = (reading) => {
98
+ const byNode = new Map();
99
+ for (const part of reading.parts) {
100
+ byNode.set(part.nodeId, { parentId: part.parentId, anchors: part.standing !== "unknown" });
101
+ }
102
+ return byNode;
103
+ };
104
+ /**
105
+ * Why a pair of one reading is not a pair of the other, given that it is not.
106
+ *
107
+ * In order, because the answers are not exclusive and the first true one is the
108
+ * one worth saying: a part that is not there is not also moved, and a part that
109
+ * cannot anchor is not also separated. `separated` is therefore the narrow
110
+ * answer it should be — both parts there, both able to anchor, still children of
111
+ * one part, and no longer next to each other.
112
+ */
113
+ const fateOf = (pair, placements, pairs) => {
114
+ const after = placements.get(pair.after);
115
+ const before = placements.get(pair.before);
116
+ if (after === undefined || before === undefined)
117
+ return "absent";
118
+ if (!after.anchors || !before.anchors)
119
+ return "unanchorable";
120
+ if (after.parentId !== before.parentId)
121
+ return "moved";
122
+ if (pairs.has(keyOf(pair.before, pair.after)))
123
+ return "reordered";
124
+ return "separated";
125
+ };
126
+ /**
127
+ * Whether two shares are at least one reader's worth apart, in integers.
128
+ *
129
+ * `|w.lost ÷ w.reached − n.lost ÷ n.reached| ≥ 1 ÷ min(w.reached, n.reached)`,
130
+ * multiplied out by both denominators and the smaller of them so that no
131
+ * division happens: a float that lands a hair under the threshold would decide
132
+ * that a reader who exists does not. Exact while the counts stay inside
133
+ * `Number.MAX_SAFE_INTEGER` under a cube, which is about a hundred thousand
134
+ * views of one part of one revision in one window.
135
+ */
136
+ const beyondOneReaderIn = (was, now) => {
137
+ const difference = Math.abs(was.lost * now.reached - now.lost * was.reached);
138
+ return difference * Math.min(was.reached, now.reached) >= was.reached * now.reached;
139
+ };
140
+ const comparedStopOf = (pair, now) => {
141
+ const improvement = pair.side.share - now.share;
142
+ return {
143
+ after: pair.after,
144
+ before: pair.before,
145
+ parentId: pair.parentId,
146
+ was: pair.side,
147
+ now,
148
+ improvement,
149
+ resolution: 1 / Math.min(pair.side.reached, now.reached),
150
+ beyondOneReader: beyondOneReaderIn(pair.side, now),
151
+ readersKept: improvement * now.reached,
152
+ };
153
+ };
154
+ /**
155
+ * The side of an unreached pair that is worth reporting: the one that reached
156
+ * somebody, where exactly one did.
157
+ *
158
+ * Both sides are true of themselves, and only one of them has a fall on it. A
159
+ * pair nobody reached on either side is filed on the earlier reading, because
160
+ * that is the baseline the question is asked against.
161
+ */
162
+ const unreachedSideOf = (pair, now) => {
163
+ const reporting = pair.side.reached === 0 && now.reached > 0;
164
+ return {
165
+ after: pair.after,
166
+ before: pair.before,
167
+ parentId: pair.parentId,
168
+ side: reporting ? "now" : "was",
169
+ fate: "unreached",
170
+ reached: reporting ? now.reached : pair.side.reached,
171
+ share: reporting ? now.share : pair.side.share,
172
+ };
173
+ };
174
+ /**
175
+ * The better of two, which is the ranking rule spelled once.
176
+ *
177
+ * `>` rather than `>=` keeps the first in reading order when two stops kept the
178
+ * same readers, the same way `progress.ts` ranks the steepest fall.
179
+ */
180
+ const moreKeptOf = (standing, next) => standing === null || next.readersKept > standing.readersKept ? next : standing;
181
+ const moreLostOf = (standing, next) => standing === null || next.readersKept < standing.readersKept ? next : standing;
182
+ /** A part's own words, as one string, so two readings' words compare in one go. */
183
+ const wordsOf = (part) => part.copy.words.join("\u0000");
184
+ const partsChangedOf = (was, now) => {
185
+ const earlier = new Map();
186
+ for (const part of was.parts)
187
+ earlier.set(part.nodeId, part);
188
+ const added = [];
189
+ const removed = [];
190
+ const moved = [];
191
+ const reworded = [];
192
+ let shared = 0;
193
+ let unreadable = 0;
194
+ for (const part of now.parts) {
195
+ const before = earlier.get(part.nodeId);
196
+ if (before === undefined) {
197
+ added.push(part.nodeId);
198
+ continue;
199
+ }
200
+ shared += 1;
201
+ if (before.parentId !== part.parentId)
202
+ moved.push(part.nodeId);
203
+ if (wordsOf(before) !== wordsOf(part))
204
+ reworded.push(part.nodeId);
205
+ else if (before.copy.unread.length > 0 || part.copy.unread.length > 0)
206
+ unreadable += 1;
207
+ }
208
+ const later = new Set(now.parts.map((part) => part.nodeId));
209
+ for (const part of was.parts)
210
+ if (!later.has(part.nodeId))
211
+ removed.push(part.nodeId);
212
+ return { shared, added, removed, moved, reworded, unreadable };
213
+ };
214
+ /**
215
+ * What a change did to the reading of a page, from a reading of each side.
216
+ *
217
+ * Handed two `PageReading`s rather than two `ReadingProgress`es, for the reason
218
+ * `readingProgressOf` is handed a reading: one input per side cannot be a
219
+ * mismatched pair, and the parts census needs the parts a progress leaves out —
220
+ * a root, and a part whose parent has no other child. The two progresses it
221
+ * derives are returned, so nothing downstream computes them twice.
222
+ */
223
+ export const readingChangeOf = (was, now) => {
224
+ const progress = { was: readingProgressOf(was), now: readingProgressOf(now) };
225
+ const empty = {
226
+ treeId: was.treeId,
227
+ revisions: { was: was.revision, now: now.revision },
228
+ audiences: comparedAudiencesOf(was, now),
229
+ progress,
230
+ stops: [],
231
+ incomparable: [],
232
+ mostKept: null,
233
+ mostLost: null,
234
+ };
235
+ if (was.treeId !== now.treeId) {
236
+ return { ...empty, parts: NO_PARTS, silence: "different-trees" };
237
+ }
238
+ /**
239
+ * Two forms of one page are two trees under one tree id, so the census is
240
+ * withheld with the stops rather than left standing: *three bands moved* read
241
+ * across two forms is the audience's own deltas presented as the change.
242
+ */
243
+ if (crossesAudiences(was, now)) {
244
+ return { ...empty, parts: NO_PARTS, silence: "different-audiences" };
245
+ }
246
+ const parts = partsChangedOf(was, now);
247
+ /**
248
+ * A side read as neither population, which is checked **before** the view
249
+ * floor because it is the cause of it: a refused page reading publishes a
250
+ * floor of nought with full counters behind it, so the floor alone reports a
251
+ * window of two forms as a window nobody read (0301).
252
+ *
253
+ * It sits below `crossesAudiences` for reading order rather than for
254
+ * precedence — the two states are mutually exclusive, so swapping them
255
+ * changes nothing. Taken off the two sides' own published scope rather than
256
+ * recomputed, which is what `audienceScopeRead` is for: the same call the
257
+ * funnel comparison makes for the same state (0300).
258
+ */
259
+ if (audienceScopeRead(was).reading === "mixed" || audienceScopeRead(now).reading === "mixed") {
260
+ return { ...empty, parts, silence: "audiences-mixed" };
261
+ }
262
+ /**
263
+ * A side with no views has no share to compare against, and the parts census
264
+ * does not need one — so the tree half of the answer stands and the reader
265
+ * half says why it is missing.
266
+ */
267
+ if (was.views === 0 || now.views === 0) {
268
+ return { ...empty, parts, silence: "nothing-measured" };
269
+ }
270
+ const earlierPairs = adjacenciesOf(progress.was);
271
+ const laterPairs = new Map();
272
+ for (const pair of adjacenciesOf(progress.now))
273
+ laterPairs.set(keyOf(pair.after, pair.before), pair);
274
+ const laterKeys = new Set(laterPairs.keys());
275
+ const earlierKeys = new Set(earlierPairs.map((pair) => keyOf(pair.after, pair.before)));
276
+ const laterPlacements = placementsOf(now);
277
+ const stops = [];
278
+ const incomparable = [];
279
+ const matched = new Set();
280
+ let mostKept = null;
281
+ let mostLost = null;
282
+ for (const pair of earlierPairs) {
283
+ const key = keyOf(pair.after, pair.before);
284
+ const later = laterPairs.get(key);
285
+ if (later === undefined) {
286
+ incomparable.push({
287
+ after: pair.after,
288
+ before: pair.before,
289
+ parentId: pair.parentId,
290
+ side: "was",
291
+ fate: fateOf(pair, laterPlacements, laterKeys),
292
+ reached: pair.side.reached,
293
+ share: pair.side.share,
294
+ });
295
+ continue;
296
+ }
297
+ matched.add(key);
298
+ if (pair.side.reached === 0 || later.side.reached === 0) {
299
+ incomparable.push(unreachedSideOf(pair, later.side));
300
+ continue;
301
+ }
302
+ const stop = comparedStopOf(pair, later.side);
303
+ stops.push(stop);
304
+ if (!stop.beyondOneReader)
305
+ continue;
306
+ if (stop.readersKept > 0)
307
+ mostKept = moreKeptOf(mostKept, stop);
308
+ if (stop.readersKept < 0)
309
+ mostLost = moreLostOf(mostLost, stop);
310
+ }
311
+ const earlierPlacements = placementsOf(was);
312
+ for (const pair of adjacenciesOf(progress.now)) {
313
+ if (matched.has(keyOf(pair.after, pair.before)))
314
+ continue;
315
+ incomparable.push({
316
+ after: pair.after,
317
+ before: pair.before,
318
+ parentId: pair.parentId,
319
+ side: "now",
320
+ fate: fateOf(pair, earlierPlacements, earlierKeys),
321
+ reached: pair.side.reached,
322
+ share: pair.side.share,
323
+ });
324
+ }
325
+ return { ...empty, parts, stops, incomparable, mostKept, mostLost, silence: null };
326
+ };
327
+ //# sourceMappingURL=change.js.map
@@ -45,6 +45,16 @@ import type { ReaderTallyStore } from "./tally.js";
45
45
  * windows is counted in both — the over-count 0147 accepts. `tally.ts` already
46
46
  * states the remedy in its own words: *a deployment that wants the bound small
47
47
  * makes the rollup window long relative to a page view.* This is that number.
48
+ * A deployment no longer has to guess whether it chose well: each run adds its
49
+ * window's page views to the counter the door counts arrivals into, so the
50
+ * difference between the two is what this setting actually cost
51
+ * (`page-views.ts`).
52
+ *
53
+ * **A run also writes down that it happened.** Applying a window stamps the
54
+ * fold's own timestamp on each revision's door row, which is what lets a
55
+ * deployment be told that nothing has folded for longer than its own schedule
56
+ * allows — the openings waiting are otherwise indistinguishable from the
57
+ * ordinary one-window lag this setting creates (0274).
48
58
  *
49
59
  * **Shorter is more anonymous.** The raw window is the entire mechanism by
50
60
  * which a view key stops existing (0146). The key is opaque, random and
@@ -132,6 +142,37 @@ export type CollectionSummary = {
132
142
  * failure mode here, so the number travels with the run that produced it.
133
143
  */
134
144
  readonly uncorrelated: number;
145
+ /**
146
+ * Of the batches counted, how many were a repeat of one already folded in
147
+ * this window and were therefore folded once (`rollup.ts`).
148
+ *
149
+ * A subset of `counted` rather than a number beside it: every one of them was
150
+ * read from the buffer and is forgotten with the rest. Non-zero every run is
151
+ * a sender retrying deliveries it already made, which is worth finding — and
152
+ * the figure is in the run's outcome rather than in a stored row because a
153
+ * fold's own numbers are not durable, only the counters it produced are.
154
+ */
155
+ readonly redelivered: number;
156
+ /**
157
+ * How old the oldest delivery the scan found was, in milliseconds, at the
158
+ * instant this run was taken.
159
+ *
160
+ * A fact about the buffer and about no reader, like every other figure here.
161
+ * It is free: a scan runs from the oldest end, so the first batch it read is
162
+ * the oldest one there is, and this is one subtraction over it.
163
+ *
164
+ * **The run does the subtraction rather than the caller**, because the
165
+ * caller's clock is not this run's: a surface that read the age against its
166
+ * own `now` would publish a number nothing had measured.
167
+ *
168
+ * Never absent and always at least the ripeness window: a summary exists only
169
+ * where something was ripe. What it is for is
170
+ * {@link retentionPromiseOf} — whether the ceiling the deployment publishes
171
+ * to its readers is one it keeps. A delivery whose stored instant cannot be
172
+ * read leaves this not a number, and that reading answers *nothing here can
173
+ * say* on it rather than *kept*.
174
+ */
175
+ readonly oldestMs: number;
135
176
  };
136
177
  export type CollectionOutcome = {
137
178
  readonly outcome: "collected";
@@ -44,6 +44,16 @@ import { rollUp } from "./rollup.js";
44
44
  * windows is counted in both — the over-count 0147 accepts. `tally.ts` already
45
45
  * states the remedy in its own words: *a deployment that wants the bound small
46
46
  * makes the rollup window long relative to a page view.* This is that number.
47
+ * A deployment no longer has to guess whether it chose well: each run adds its
48
+ * window's page views to the counter the door counts arrivals into, so the
49
+ * difference between the two is what this setting actually cost
50
+ * (`page-views.ts`).
51
+ *
52
+ * **A run also writes down that it happened.** Applying a window stamps the
53
+ * fold's own timestamp on each revision's door row, which is what lets a
54
+ * deployment be told that nothing has folded for longer than its own schedule
55
+ * allows — the openings waiting are otherwise indistinguishable from the
56
+ * ordinary one-window lag this setting creates (0274).
47
57
  *
48
58
  * **Shorter is more anonymous.** The raw window is the entire mechanism by
49
59
  * which a view key stops existing (0146). The key is opaque, random and
@@ -149,15 +159,80 @@ export const collectReaderSignals = async (journal, store, request = {}) => {
149
159
  const plan = collectionPlanOf(scanned.batches, horizon);
150
160
  if (plan.before === null)
151
161
  return { outcome: "nothing-ripe", waiting: plan.waiting };
152
- const rollup = rollUp(plan.ripe, { ...(request.pairs ? { pairs: request.pairs } : {}) });
162
+ /**
163
+ * **One fold per audience, not one per window** (0284).
164
+ *
165
+ * A window holds whatever arrived in it, and once a deployment serves two
166
+ * forms of a page that is two audiences' batches interleaved. Folding them
167
+ * together would add two populations into one counter — the failure the
168
+ * record behind this exists to prevent, and the one that cannot be undone
169
+ * afterwards, because the rows that would say which form a reader saw are the
170
+ * rows being summed.
171
+ *
172
+ * So the ripe batches are grouped by the audience they were filed under and
173
+ * each group is folded on its own, then **all of them are written together**
174
+ * (0316). `rollUp` stays audience-blind: it is handed one audience's batches
175
+ * and knows nothing about the dimension, which is what keeps the fold a pure
176
+ * function of a window.
177
+ *
178
+ * The summary adds up across audiences, because it describes the run rather
179
+ * than any one population.
180
+ */
181
+ const byAudience = new Map();
182
+ for (const batch of plan.ripe) {
183
+ const group = byAudience.get(batch.audienceId);
184
+ if (group === undefined)
185
+ byAudience.set(batch.audienceId, [batch]);
186
+ else
187
+ group.push(batch);
188
+ }
189
+ const folded = [...byAudience].map(([audience, batches]) => ({
190
+ audience,
191
+ rollup: rollUp(batches, { ...(request.pairs ? { pairs: request.pairs } : {}) }),
192
+ }));
193
+ /**
194
+ * The oldest delivery in the buffer, which is the first batch the scan read:
195
+ * it runs from the oldest end and the ripe prefix starts there.
196
+ *
197
+ * There is always one wherever a summary is built — `plan.before` is a
198
+ * position taken off the last ripe batch, so a plan carrying one has a first
199
+ * — and the unreachable branch is a parse of nothing rather than a nought on
200
+ * purpose. A nought would say *a delivery that arrived this instant*, which
201
+ * is the strongest answer the retention reading can give; a figure that is
202
+ * not a number makes it answer that nothing here can say.
203
+ */
204
+ const oldest = plan.ripe[0]?.receivedAt ?? "";
153
205
  const summary = {
154
206
  counted: plan.ripe.length,
155
- tallies: rollup.tallies.length,
156
- funnels: rollup.funnels.length,
157
- views: rollup.views,
158
- uncorrelated: rollup.uncorrelated,
207
+ oldestMs: Date.parse(now) - Date.parse(oldest),
208
+ tallies: folded.reduce((total, { rollup }) => total + rollup.tallies.length, 0),
209
+ funnels: folded.reduce((total, { rollup }) => total + rollup.funnels.length, 0),
210
+ views: folded.reduce((total, { rollup }) => total + rollup.views, 0),
211
+ uncorrelated: folded.reduce((total, { rollup }) => total + rollup.uncorrelated, 0),
212
+ redelivered: folded.reduce((total, { rollup }) => total + rollup.redelivered, 0),
159
213
  };
160
- const applied = await store.apply(rollup, now);
214
+ /**
215
+ * **One write for the whole window, every audience in it** (0316).
216
+ *
217
+ * One call per audience is what this was, and it had a state between the
218
+ * calls that nothing could get out of: the audiences already applied were
219
+ * durable, the rest were not, and the buffer still held the window — because
220
+ * counting and forgetting are one operation, which is the invariant at the
221
+ * top of this file. So the next run folded the same batches again and **added
222
+ * the already-durable audiences a second time**, permanently (0158), on the
223
+ * five of nine counters that are occurrences rather than distinct counts.
224
+ * `unavailable` said *nothing became durable* while that was happening.
225
+ *
226
+ * It is one `applyWindow` now, so there is no state to get out of and the
227
+ * sentence on `unavailable` is true again. Nothing is reported about it
228
+ * because there is nothing left to report.
229
+ */
230
+ const applied = await store.applyWindow(folded.map(({ audience, rollup }) => ({
231
+ audience,
232
+ tallies: rollup.tallies,
233
+ funnels: rollup.funnels,
234
+ appearances: rollup.appearances,
235
+ })), now);
161
236
  if (!applied.ok)
162
237
  return { outcome: "unavailable", error: applied.error };
163
238
  const forgotten = await journal.forget({ before: plan.before });
@@ -178,11 +253,17 @@ export const collectReaderSignals = async (journal, store, request = {}) => {
178
253
  };
179
254
  const batches = (count) => `${count} ${count === 1 ? "batch" : "batches"}`;
180
255
  const uncorrelated = (summary) => summary.uncorrelated === 0 ? "" : `, ${summary.uncorrelated} with no view key`;
256
+ /**
257
+ * Said only when there were some, in the same clause-after-the-count shape
258
+ * `uncorrelated` uses, because a line that always carries a nought trains an
259
+ * operator to stop reading it.
260
+ */
261
+ const redelivered = (summary) => summary.redelivered === 0 ? "" : `, ${summary.redelivered} delivered again and folded once`;
181
262
  /** One line for an operator, because an outcome nobody can read is one nobody acts on. */
182
263
  export const describeCollection = (outcome) => {
183
264
  switch (outcome.outcome) {
184
265
  case "collected":
185
- return `counted ${batches(outcome.summary.counted)} into ${outcome.summary.tallies} ${outcome.summary.tallies === 1 ? "tally" : "tallies"} over ${outcome.summary.views} ${outcome.summary.views === 1 ? "view" : "views"}${uncorrelated(outcome.summary)}, and forgot ${outcome.removed}${outcome.more ? " — more is waiting" : ""}`;
266
+ return `counted ${batches(outcome.summary.counted)} into ${outcome.summary.tallies} ${outcome.summary.tallies === 1 ? "tally" : "tallies"} over ${outcome.summary.views} ${outcome.summary.views === 1 ? "view" : "views"}${uncorrelated(outcome.summary)}${redelivered(outcome.summary)}, and forgot ${outcome.removed}${outcome.more ? " — more is waiting" : ""}`;
186
267
  case "nothing-ripe":
187
268
  return `nothing old enough to count${outcome.waiting === 0 ? "" : `, ${batches(outcome.waiting)} waiting`}`;
188
269
  case "counted-not-forgotten":