@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,866 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { TreeId } from "../ids.js";
3
+ import { type Result } from "../result.js";
4
+ import type { LoomTree } from "../tree/tree.js";
5
+ import { type PageForm } from "./audiences.js";
6
+ import type { ReaderSignalStoreError } from "./journal.js";
7
+ import type { LibraryWindow } from "./library-reach-change.js";
8
+ import type { StoredPageViews } from "./page-views.js";
9
+ import { type PageReading, type PartDeclarations } from "./parts.js";
10
+ import { type ReaderRegionStore, type RegionReading, type RegionReadingOptions, type StoredRegionCount } from "./region.js";
11
+ import type { ReaderTallyStore, StoredFunnel, StoredTally, TallyReadRequest } from "./tally.js";
12
+ /**
13
+ * The step between a store and a question: read a window of counters, and join
14
+ * it to the trees and the registry the counters were filed against.
15
+ *
16
+ * Thirty-eight readings sit on the other side of this and every one of them is
17
+ * a pure function of a {@link PageReading} — or of a list of them, or of two
18
+ * held against each other. Nothing in this subsystem turned a store into one,
19
+ * and nothing turned a window into the **pair** the last of those three shapes
20
+ * takes.
21
+ * A caller that wanted *which parts of this page get read* had to know that the
22
+ * counters come from `tallies`, the denominator from `pageViews`, the funnel
23
+ * answers from `funnels` and the map from a second store; that a tree and a
24
+ * registry have to be found for each revision the rows name; and that the rows
25
+ * must be sliced before the join rather than after, because `pageReadingOf`
26
+ * counts what it was handed wrongly rather than refusing it (`foreign`).
27
+ *
28
+ * So the aggregates were askable in principle and unaskable in practice, and
29
+ * that is the gap this closes. After this, the deployment-wide order over pages
30
+ * is two lines:
31
+ *
32
+ * ```ts
33
+ * const window = await readReaderWindow({ tallies: store })
34
+ * if (!window.ok) return window
35
+ * const { pages } = windowReadingsOf(window.value, treesIn(trees), registry)
36
+ * const order = deploymentReadingOf(pages.map(readingProgressOf), window.value.pageViews)
37
+ * ```
38
+ *
39
+ * ## It composes published rules and adds no figure of its own
40
+ *
41
+ * Nothing here counts, divides, sums or withholds. The audience census is
42
+ * `audiencesIn`, what makes two readings one page is `readingKeyOf` (0290), the
43
+ * three-way answer about a population is `audienceScopeOf` inside the join
44
+ * (0300), and the join itself is `pageReadingOf` unchanged. This module decides
45
+ * one thing — **which readings a window holds** — and hands each of them the
46
+ * rows it is a reading of.
47
+ *
48
+ * That is deliberately the whole of it. A rung that also added up what it
49
+ * joined would be a thirty-ninth reading nobody asked for, and the
50
+ * double-count every reading above it already guards would have a second
51
+ * place to go wrong.
52
+ *
53
+ * ## The one reading that was two steps, and the one argument it needs
54
+ *
55
+ * The region map was the exception and it was a gap named when this was
56
+ * written. Every other reading follows from a {@link PageReading} or a list of
57
+ * them; the region rows were carried on the window, counted in the form census
58
+ * so a form named only by a bucket still got a reading, and joined into nothing
59
+ * — because {@link regionReadingOf} takes a **floor**, the floor is
60
+ * per-deployment configuration (§7), and this rung reads no configuration.
61
+ *
62
+ * It still does not read any. The floor is {@link WindowReadingOptions},
63
+ * handed in with the call, and `regionFloorOf` underneath is raise-only — so
64
+ * the rung holds one piece of configuration it was given rather than one it
65
+ * went looking for, which is the line §7 already draws. What that closes is
66
+ * the half that was quietly wrong: a caller who passed nothing got the default
67
+ * rather than the deployment's floor, and nothing in the types said so.
68
+ *
69
+ * {@link WindowReadings.regions} is therefore both answers at once — one map
70
+ * per revision per form, keyed so `readingKeyOf` pairs it with that form's page
71
+ * reading, **and** the deployment's readership whole. Both, because the floor
72
+ * bites harder the narrower the group: thirty views of one country split across
73
+ * two forms are a readership the whole map names and both split maps withhold
74
+ * (0297).
75
+ *
76
+ * ## The second step, which is the pair
77
+ *
78
+ * A window joined to its pages answers every reading that is a function of one
79
+ * {@link PageReading}. Nine comparisons are functions of **two**, and a window
80
+ * holds both sides of most of them — one page's revision 5 and its revision 9
81
+ * are two readings in the same list. {@link windowPairsOf} is the step that
82
+ * says which two, under the one published rule a comparison pairs on (0293),
83
+ * so that a caller composing *what did this change do* across a deployment
84
+ * never writes the pairing itself.
85
+ *
86
+ * ## The third step, which is the two libraries
87
+ *
88
+ * Five of those nine take two readings and the other four take two whole
89
+ * libraries, which the pairs alone cannot be arranged into: a form the window
90
+ * holds one revision of is a page published, a page withdrawn or a page nobody
91
+ * touched, and no counter row tells them apart. {@link windowLibrariesOf} takes
92
+ * the placing as an argument — the shape the region floor took, configuration
93
+ * held rather than looked for — and names the forms nobody could place instead
94
+ * of guessing one onto a side.
95
+ *
96
+ * ## Why the trees are the caller's to resolve
97
+ *
98
+ * This lane holds counters, not pages. A tree lives in the tree store, which is
99
+ * another lane's, and reaching into it from here would make the reading path
100
+ * depend on the write path for the sake of a lookup the caller can do better:
101
+ * it knows whether it holds the revisions already, whether it wants them in one
102
+ * query or forty, and what to do when one is gone.
103
+ *
104
+ * So {@link revisionsIn} says which revisions the rows name and
105
+ * {@link RevisionTrees} is how the answers come back — the same bargain
106
+ * {@link PartDeclarations} struck with the registry (0114, 0122): a shape a
107
+ * real store satisfies and a two-line double in a test satisfies as well.
108
+ *
109
+ * Pure apart from {@link readReaderWindow}, which is the one function here that
110
+ * touches a store. No clock, no DOM, no import that reaches a package.
111
+ */
112
+ /** The stores a window is read from. */
113
+ export type ReaderWindowSources = {
114
+ /** The counters, the funnel answers and the door rows. */
115
+ readonly tallies: Pick<ReaderTallyStore, "tallies" | "funnels" | "pageViews">;
116
+ /**
117
+ * Where readers were, which is a second store and an optional one.
118
+ *
119
+ * A deployment that never configured one is not a deployment whose readers
120
+ * were nowhere, so an absent store and an empty map are kept apart all the
121
+ * way to {@link ReaderWindow.regions}.
122
+ */
123
+ readonly regions?: Pick<ReaderRegionStore, "regions">;
124
+ };
125
+ /**
126
+ * One window of counters, as the stores answered.
127
+ *
128
+ * Rows as they came back: nothing is summed, deduplicated, reordered or
129
+ * dropped. The distinct counts in them cannot be added (0147) and the readings
130
+ * downstream each know which of their figures may be, so a rung that tidied
131
+ * them would be making that decision for all of them at once and in the one
132
+ * place that knows least about it.
133
+ */
134
+ export type ReaderWindow = {
135
+ readonly tallies: readonly StoredTally[];
136
+ readonly funnels: readonly StoredFunnel[];
137
+ readonly pageViews: readonly StoredPageViews[];
138
+ /**
139
+ * The region buckets, or `undefined` where no region store was offered.
140
+ *
141
+ * `undefined` is *nothing here can say* and `[]` is *the store holds none*,
142
+ * which is the distinction this subsystem draws everywhere else it has two
143
+ * such states (0240). A surface that reads them alike reports *we do not
144
+ * know where your readers are* as *you have no readers abroad*.
145
+ */
146
+ readonly regions: readonly StoredRegionCount[] | undefined;
147
+ };
148
+ /**
149
+ * Read one window from the stores, with one scope rather than four.
150
+ *
151
+ * The four reads are independent and are made together. The first failure is
152
+ * the answer: a window half of whose rows arrived is not a narrower window, it
153
+ * is a reading whose every rate has a denominator from one read and a numerator
154
+ * from another, and the figures would look plausible.
155
+ *
156
+ * The request is the stores' own {@link TallyReadRequest}, passed through
157
+ * unchanged to each of them, so scoping a screen to one page, one revision or
158
+ * one audience is the one argument it already was.
159
+ */
160
+ export declare const readReaderWindow: (sources: ReaderWindowSources, request?: TallyReadRequest) => Promise<Result<ReaderWindow, ReaderSignalStoreError>>;
161
+ /** One revision of one page, which is what a tree has to be found for. */
162
+ export type WindowRevision = {
163
+ readonly treeId: TreeId;
164
+ readonly revision: number;
165
+ };
166
+ /**
167
+ * Every revision the window's rows name, deduplicated and in a stable order.
168
+ *
169
+ * **Taken over all four row sets and not only the counters.** A revision whose
170
+ * door opened and whose window no rollup has folded yet has page view rows and
171
+ * no tallies, and it is a page a deployment most wants to see rather than one
172
+ * to leave out: it is the difference between *nobody read this* and *nothing
173
+ * has counted this yet*, which the reach reading publishes as `uncounted` and
174
+ * can only publish about a revision it was handed.
175
+ *
176
+ * The audience is deliberately not part of this. A tree is one tree at one
177
+ * revision however many forms of it are served — two forms are the deltas an
178
+ * audience earns over one base (0263) — so asking for a tree per form would be
179
+ * asking the caller for the same tree twice.
180
+ */
181
+ export declare const revisionsIn: (window: ReaderWindow) => readonly WindowRevision[];
182
+ /**
183
+ * Where the trees come from, as the join needs to see it.
184
+ *
185
+ * A function rather than a list, for the reason the registry declarations are
186
+ * one: a deployment holding its revisions in a store, a cache, or a map it
187
+ * built for this call all satisfy it, and so does a one-line double.
188
+ */
189
+ export type RevisionTrees = {
190
+ /** The tree at that revision, or `undefined` where this source has none. */
191
+ readonly treeFor: (where: WindowRevision) => LoomTree | undefined;
192
+ };
193
+ /**
194
+ * The trees a caller already holds, as a source.
195
+ *
196
+ * Keyed by tree **and** revision, because two revisions of one page are two
197
+ * trees to this join and keying by the page would answer one of them for both.
198
+ * The first of two trees at one revision wins and the second is ignored: they
199
+ * disagree about what a revision is, nothing here can say which is right, and
200
+ * a silent last-wins would make the answer depend on the order a store
201
+ * returned.
202
+ */
203
+ export declare const treesIn: (trees: Iterable<LoomTree>) => RevisionTrees;
204
+ /** Why a revision the rows name has no reading. */
205
+ export type UnjoinedCause =
206
+ /**
207
+ * The source has no tree at that revision.
208
+ *
209
+ * Ordinary rather than broken: counters outlive the revision they were filed
210
+ * against, so a deployment that has pruned old trees, or scoped its lookup to
211
+ * the revisions it draws, has rows here it cannot read. It is published
212
+ * rather than dropped because the rows are a page's readers, and a screen
213
+ * that silently left them out would under-report a deployment by however many
214
+ * revisions it could not find.
215
+ */
216
+ "no-tree"
217
+ /**
218
+ * The source answered with a different page or a different revision from the
219
+ * one asked for.
220
+ *
221
+ * A source's own fault, and the one worth refusing loudly: reading one
222
+ * revision's counters against another revision's tree answers every question
223
+ * on the page with confident nonsense, because the node ids line up often
224
+ * enough to look right. This is the mistake `foreign` was put on a reading to
225
+ * catch, caught one rung earlier where it can still be refused.
226
+ */
227
+ | "mismatched";
228
+ /** The closed set, for a surface accounting for every revision it cannot draw. */
229
+ export declare const UNJOINED_CAUSES: readonly UnjoinedCause[];
230
+ /** One line per cause, for a surface saying why a page is not on the screen. */
231
+ export declare const describeUnjoinedCause: (cause: UnjoinedCause) => string;
232
+ /** A revision whose rows could not be joined, and why. */
233
+ export type UnjoinedRevision = WindowRevision & {
234
+ readonly cause: UnjoinedCause;
235
+ /** Counter rows left unread, so the cost of not drawing it is a number. */
236
+ readonly tallies: number;
237
+ };
238
+ /**
239
+ * A region map the window joined, keyed so it pairs with the page reading of
240
+ * the same form.
241
+ *
242
+ * `treeId`, `revision` and `audienceId` are exactly {@link ReadingOfAudience},
243
+ * so `readingKeyOf` takes one of these as it takes a {@link PageReading} and a
244
+ * screen holding both lists pairs them on the one rule (0290) rather than on a
245
+ * spelling of its own.
246
+ */
247
+ export type WindowRegionReading = WindowRevision & {
248
+ /**
249
+ * The form these arrivals were served, or `null` where the rows named none.
250
+ *
251
+ * `null` is *no row said*, which is a window written before the column
252
+ * existed (0284) and every window a test builds by hand — not `aud_everyone`,
253
+ * which would be asserting a name nobody wrote (0294).
254
+ */
255
+ readonly audienceId: AudienceId | null;
256
+ /** The map itself, floored, as {@link regionReadingOf} reads it. */
257
+ readonly reading: RegionReading;
258
+ };
259
+ /** Where a window's readers were, at the floor the caller handed in. */
260
+ export type WindowRegionReadings = {
261
+ /**
262
+ * One map per revision, per form, in a stable order.
263
+ *
264
+ * **The groups are the region rows' own audience column**, rather than the
265
+ * forms the other row sets name. Every row is then in exactly one map by
266
+ * construction, which is what makes {@link WindowRegionReadings.readership}
267
+ * and these add to the same number of views; grouping by a form named
268
+ * elsewhere would leave a row naming none in no map at all, and a map holding
269
+ * no rows is not a form a deployment has arrivals for.
270
+ */
271
+ readonly maps: readonly WindowRegionReading[];
272
+ /**
273
+ * The deployment's readership, over every row in the window.
274
+ *
275
+ * **Published beside the per-form maps rather than instead of them, because
276
+ * the floor bites harder the narrower the group** — the same sentence
277
+ * `regionReadingFor` carries. Thirty views of one country split twelve and
278
+ * eighteen across two forms are a readership the whole map names and both
279
+ * form maps withhold. A rung that published only the split would answer
280
+ * *where are my readers* worse than the two calls it replaces.
281
+ *
282
+ * Summing two forms' arrivals is right here and wrong on the counters, and
283
+ * the asymmetry is a published one (0297): a person who arrived arrived once,
284
+ * whichever form they were served, while adding two forms' node counters is
285
+ * one number about two pages.
286
+ */
287
+ readonly readership: RegionReading;
288
+ /**
289
+ * Rows beyond the first for one tree, revision, form and region — dropped
290
+ * from every map, and counted here.
291
+ *
292
+ * A store keeps one row per that key, so this cannot come out of one read: it
293
+ * is a caller concatenating two windows whose counts are already running
294
+ * totals. Adding them would double a bucket, which is the one error here that
295
+ * cannot be undone afterwards (0158), so the first row stands and the fact is
296
+ * a number. The same rule `regionReadingFor` applies to one revision, applied
297
+ * once to the whole window so the maps and the readership drop the same rows.
298
+ */
299
+ readonly duplicated: number;
300
+ };
301
+ /** What the join was asked to read the regions at. */
302
+ export type WindowReadingOptions = RegionReadingOptions;
303
+ /** The rows one region map may be read from, and the repeats it dropped. */
304
+ export type DistinctRegionRows = {
305
+ /** The first row for each tree, revision, form and region, in the order they arrived. */
306
+ readonly kept: readonly StoredRegionCount[];
307
+ /** Rows beyond the first for one of those keys, which are in {@link kept} nowhere. */
308
+ readonly duplicated: number;
309
+ };
310
+ /**
311
+ * The rows of a window with the repeats of one bucket dropped, which is the one
312
+ * thing every reading of a region row set has to do first.
313
+ *
314
+ * A store keeps one row per tree, revision, form and region, so this cannot
315
+ * come out of one read: it is a caller concatenating two windows whose counts
316
+ * are already running totals. **Adding them doubles a bucket**, which is the one
317
+ * error in this subsystem that cannot be undone afterwards (0158), and a doubled
318
+ * bucket is worse than a wrong number — it clears a floor it should not have
319
+ * cleared, so a place with too few readers to name gets named.
320
+ *
321
+ * Published because it is used twice and was written once. {@link
322
+ * WindowRegionReadings} folds it into the maps it builds; a reading that takes
323
+ * the **rows** rather than the maps — which is `regionPagesOf`, because a
324
+ * breakdown by page needs the cells and a map does not hold them — has to apply
325
+ * the same rule to the same rows or the two answers disagree about one window.
326
+ * Two spellings of one rule that agree today are a thing this subsystem has
327
+ * been bitten by before (0265).
328
+ *
329
+ * Linear in the rows, with one set.
330
+ */
331
+ export declare const distinctRegionRows: (rows: readonly StoredRegionCount[]) => DistinctRegionRows;
332
+ /** What a window came to once its rows were joined to the pages they are about. */
333
+ export type WindowReadings = {
334
+ /**
335
+ * One reading per page, per revision, per form — which is what one reading is
336
+ * (0290) — in a stable order.
337
+ *
338
+ * Never two of one: the key every reading above this refuses to count twice
339
+ * on is the key the window was split by, so a caller may sum across this list
340
+ * on any figure the reading it derives says may be summed.
341
+ */
342
+ readonly pages: readonly PageReading[];
343
+ /** Revisions the rows name that have no reading, in the same order. */
344
+ readonly unjoined: readonly UnjoinedRevision[];
345
+ /**
346
+ * Where the readers were, or `undefined` where no region store was offered.
347
+ *
348
+ * The `undefined` is {@link ReaderWindow.regions}' own, carried rather than
349
+ * collapsed (0309): *we cannot say where your readers are* and *you have no
350
+ * readers abroad* are two sentences, and `[]` holds the second — a window
351
+ * whose store answered with nothing reads as a readership of no views rather
352
+ * than as no readership.
353
+ *
354
+ * **A map here is not held to a tree.** The maps are of arrivals, which need
355
+ * no tree to be read against, so a revision in {@link WindowReadings.unjoined}
356
+ * still has its readers counted. Dropping them would under-report a
357
+ * deployment that has pruned old trees by exactly the readers it has least
358
+ * other record of, and it would make the maps and the readership disagree.
359
+ */
360
+ readonly regions: WindowRegionReadings | undefined;
361
+ };
362
+ /**
363
+ * Join a window of counters to the pages it is about.
364
+ *
365
+ * **One reading per form, rather than one per revision read as neither.** A
366
+ * window holding two audiences at one revision is ambiguous to the join
367
+ * underneath — it reads neither, names both, and `health.ts` reports the fault
368
+ * (0290, 0300) — and that refusal is right for a caller that was handed a
369
+ * window and asked nothing. Here the question is *what does this window hold*,
370
+ * and the answer is both forms: the ambiguity was never in the rows, which say
371
+ * which form each belongs to, it was in asking one question of two
372
+ * populations. So the split is made rather than refused, and each form's
373
+ * reading is of its own readers.
374
+ *
375
+ * **The region maps are joined beside the pages and not under them.** They are
376
+ * maps of arrivals rather than of nodes, so they need no tree: a revision whose
377
+ * tree is gone is `unjoined` for its counters and still has its readers
378
+ * counted. See {@link WindowReadings.regions}.
379
+ *
380
+ * **Each reading is handed its revision's rows and told which form to read.**
381
+ * Not the window — a reading handed the whole of one would count every other
382
+ * page's rows as `foreign`, which is exactly what that field exists to report —
383
+ * and not one form's rows either, because then a reading could not say that the
384
+ * page has another form at all. `foreign` is therefore nought on every reading
385
+ * this produces, `audiences` is what the revision really holds, and
386
+ * `otherAudience` is the other form's rows, counted apart and not read.
387
+ */
388
+ export declare const windowReadingsOf: (window: ReaderWindow, trees: RevisionTrees, declarations: PartDeclarations, options?: WindowReadingOptions) => WindowReadings;
389
+ /**
390
+ * A page in one form, with the two revisions of it a comparison is of.
391
+ *
392
+ * It is a {@link PageForm}, so `formKeyOf` takes one of these as it takes a
393
+ * reading and a surface holding both lists pairs them on the published rule
394
+ * (0293) rather than on a spelling of its own. The audience is the form's and
395
+ * therefore both sides' — see {@link windowPairsOf}.
396
+ *
397
+ * Not a funnel pair, which is two stops inside one reading (`funnel.ts`). This
398
+ * is two readings of one page.
399
+ */
400
+ export type WindowPair = PageForm & {
401
+ /** The earlier side. Its revision is always below `now`'s. */
402
+ readonly was: PageReading;
403
+ readonly now: PageReading;
404
+ /**
405
+ * Revisions of this form the window holds below `was`, oldest first.
406
+ *
407
+ * Empty for the ordinary case of two. A deployment that has published three
408
+ * times inside one window has an older change in its counters, and this is
409
+ * how a surface says *and one earlier revision* rather than how it reads one:
410
+ * the pair for it is two of {@link WindowReadings.pages} and
411
+ * `readingChangeOf`, which is the same call this makes.
412
+ */
413
+ readonly superseded: readonly number[];
414
+ };
415
+ /**
416
+ * A form the window holds one revision of, so there is nothing to compare it
417
+ * against.
418
+ *
419
+ * Ordinary rather than broken, and published rather than dropped for the reason
420
+ * {@link UnjoinedRevision} is: a page published inside the window, a page
421
+ * nobody has changed since the window began, and the two sides of a deployment
422
+ * that upgraded across 0284 all land here, and a screen that left them out
423
+ * would show a deployment fewer pages than it has.
424
+ */
425
+ export type UnpairedForm = PageForm & {
426
+ /** The one reading of it, carried so a surface drawing the page still has it. */
427
+ readonly reading: PageReading;
428
+ };
429
+ /** What a window came to once its readings were paired into before-and-afters. */
430
+ export type WindowPairs = {
431
+ /** One per form that has two revisions in the window, in a stable order. */
432
+ readonly pairs: readonly WindowPair[];
433
+ /** The forms that have one, in the same order. */
434
+ readonly unpaired: readonly UnpairedForm[];
435
+ /**
436
+ * Readings handed in twice under one `readingKeyOf`, dropped before pairing.
437
+ *
438
+ * Nought for anything {@link windowReadingsOf} produced, which never holds
439
+ * two readings of one key. It is not nought for a caller that concatenated
440
+ * two windows' readings, and the repeat has to be dropped rather than paired:
441
+ * a form whose latest revision arrived twice would otherwise pair that
442
+ * revision with itself and publish *nothing changed* about a change.
443
+ */
444
+ readonly duplicated: number;
445
+ };
446
+ /**
447
+ * Pair a window's readings into the before-and-afters the comparisons take.
448
+ *
449
+ * The second step of this rung and the one it left undone. Nine comparisons in
450
+ * this subsystem take two sides — `readingChangeOf`, `copyChangeOf`,
451
+ * `paceChangeOf`, `actionChangeOf`, `funnelChangeOf` and the four library
452
+ * comparisons — and not one of them could be reached from a store, because
453
+ * nothing turned a window into a pair. `deploymentChangeOf` says so in its own
454
+ * words: *a caller with two windows of counters reads each page's parts, then
455
+ * its progress, then its comparison, then this.* The pairing was the step with
456
+ * no owner, and a caller writing it is a caller writing 0293 again.
457
+ *
458
+ * After this the deployment-wide order over what a change did is three lines:
459
+ *
460
+ * ```ts
461
+ * const { pages } = windowReadingsOf(window, treesIn(trees), registry)
462
+ * const { pairs } = windowPairsOf(pages)
463
+ * const order = deploymentChangeOf(
464
+ * pairs.map(({ was, now }) => readingChangeOf(was, now)),
465
+ * window.pageViews
466
+ * )
467
+ * ```
468
+ *
469
+ * ## One pair per form, and it is the latest two revisions
470
+ *
471
+ * A form with revisions 3, 5 and 9 in the window has two consecutive pairs in
472
+ * it and this produces one: 5 against 9. Publishing both would make the page
473
+ * unreadable by the only consumer there is — `deploymentChangeOf` gates a form
474
+ * handed two different revision pairs as `ambiguous` and drops it, which is
475
+ * right of it, because *which page did the change hurt most* cannot be answered
476
+ * about a form that changed twice. So every page a deployment published three
477
+ * times inside one window would vanish from the order, and the figure it
478
+ * vanished out of would go on looking right (0158).
479
+ *
480
+ * The latest pair rather than the widest one, for the same reason: 3 against 9
481
+ * is two changes added together and labelled as one, and *what did this change
482
+ * do* is a question about the change that was made. What the window holds below
483
+ * `was` is on the pair as {@link WindowPair.superseded}, so nothing is hidden
484
+ * and an older pair is two readings and one call away.
485
+ *
486
+ * ## Paired by the form rule and nothing else, so no pair here can be refused
487
+ *
488
+ * The grouping is `formKeyOf` (0293), so both sides of every pair are of one
489
+ * tree and one audience by construction. Three of the four states
490
+ * `readingChangeOf` refuses are therefore unreachable from a pair this makes:
491
+ * `different-trees` needs two trees, `different-audiences` needs two named
492
+ * audiences, and `audiences-mixed` needs a side that holds two forms and names
493
+ * none, which is a reading {@link windowReadingsOf} does not produce — it
494
+ * splits a revision serving two forms into one reading each. What is left is
495
+ * `nothing-measured`, which is about the readers rather than about the pairing,
496
+ * and that is the division this rung is for: a comparison that comes back
497
+ * silent from here is silent about a deployment's readers and not about its
498
+ * caller.
499
+ *
500
+ * **The one pair it will not make, which is deliberate.** A deployment that
501
+ * upgraded across 0284 has revisions whose rows name no audience and revisions
502
+ * whose rows name one, and those are two forms under the published rule. So the
503
+ * comparison spanning the upgrade is not produced, and both of its sides are in
504
+ * {@link WindowPairs.unpaired}. It is the pair `crossesAudiences` deliberately
505
+ * allows — unprovable rather than proven alike — and allowing it is not the
506
+ * same as asserting it: nothing in the rows says the two are one population, a
507
+ * rung that paired them would be a tenth spelling of the pairing rule, and the
508
+ * caller who knows its own history makes that comparison in one call, where
509
+ * `audiences` on the result says what it was read across.
510
+ *
511
+ * ## It adds no figure of its own
512
+ *
513
+ * Nothing here counts, divides, sums or withholds, which is the rule the first
514
+ * step of this rung set: it decides **which pairs a window holds** and hands
515
+ * each of them the two readings it is a pair of. Every one of the nine
516
+ * comparisons is one call off a pair.
517
+ *
518
+ * **It does not assemble the two windows the four library comparisons take.**
519
+ * Those compare a whole library before against a whole library after, and a
520
+ * form with one revision cannot be put on a side out of anything here: a page
521
+ * published inside the window belongs to the later one, a page nobody has
522
+ * changed belongs to both, and nothing in the counters tells them apart.
523
+ * {@link windowLibrariesOf} is that step, and it asks the caller — the only
524
+ * party that knows what it published when — rather than guessing, because
525
+ * guessing publishes a page nobody touched as a page gained (0295). What this
526
+ * owes it is the two lists, which is why {@link WindowPairs.unpaired} is
527
+ * published rather than dropped.
528
+ *
529
+ * Linear in the readings but for one sort per form, which is a sort of that
530
+ * form's revisions and not of the window: the window sorted whole would be the
531
+ * shape rule 4 holds this subsystem to, and a deployment's revisions per page
532
+ * are a handful where its pages are not.
533
+ */
534
+ export declare const windowPairsOf: (readings: readonly PageReading[]) => WindowPairs;
535
+ /**
536
+ * Where a form the window holds one revision of belongs, which is the one
537
+ * thing in this rung the counters cannot answer.
538
+ *
539
+ * A form with two revisions is in both libraries by construction — its earlier
540
+ * revision is the page the earlier library held and its later one is the page
541
+ * the later library holds. A form with **one** is three different pages
542
+ * wearing one shape, and nothing in a counter row tells them apart: a
543
+ * `StoredTally.updatedAt` is when the fold last touched the row, not when the
544
+ * page was published, and a door row's is the same. The only party that knows
545
+ * is the deployment, which knows what it published when.
546
+ */
547
+ export type FormPlacing =
548
+ /**
549
+ * First served inside the window: the later library holds it and the earlier
550
+ * one did not.
551
+ *
552
+ * This is the figure a library comparison exists to report — `pagesGained`,
553
+ * and `formsGained` where the page was already served in another form
554
+ * (0295). A deployment that published two pages this week and had them left
555
+ * out would read `pagesGained: 0` beside them.
556
+ */
557
+ "published"
558
+ /**
559
+ * Served when the window began and not at its end: the earlier library held
560
+ * it and the later one does not.
561
+ *
562
+ * The mirror, and `pagesLost`. Its counters are in the window because readers
563
+ * reached it before it went, which is exactly why leaving it out understates
564
+ * what the deployment changed.
565
+ */
566
+ | "withdrawn"
567
+ /**
568
+ * Served throughout and never republished: both libraries hold it, at the one
569
+ * revision there is.
570
+ *
571
+ * The page contributes no movement — its placements pair with themselves —
572
+ * and it does contribute its size, which is what keeps `pages` a count of the
573
+ * library rather than a count of the pages that changed.
574
+ */
575
+ | "unchanged";
576
+ /** The closed set, for a surface accounting for every form it was asked about. */
577
+ export declare const FORM_PLACINGS: readonly FormPlacing[];
578
+ /** One line per placing, for a surface saying which library a page is in and why. */
579
+ export declare const describeFormPlacing: (placing: FormPlacing) => string;
580
+ /**
581
+ * Where the placings come from, as the libraries need to see them.
582
+ *
583
+ * A function rather than a list, for the reason {@link RevisionTrees} is one
584
+ * and {@link PartDeclarations} is: a deployment holding its publishing history
585
+ * in a store, a cache, or a map it built for this call all satisfy it, and so
586
+ * does a one-line double.
587
+ *
588
+ * `undefined` is an answer and not a gap — *this deployment cannot say* — and
589
+ * the form is reported in {@link WindowLibraries.unplaced} rather than guessed
590
+ * onto a side.
591
+ */
592
+ export type FormPlacings = {
593
+ /** Where that form belongs, or `undefined` where this source cannot say. */
594
+ readonly placingFor: (form: PageForm) => FormPlacing | undefined;
595
+ };
596
+ /** One form a deployment has placed, as {@link placingsIn} takes them. */
597
+ export type PlacedForm = PageForm & {
598
+ readonly placing: FormPlacing;
599
+ };
600
+ /**
601
+ * The placings a caller already holds, as a source.
602
+ *
603
+ * Keyed by the published form rule (0293), so a page served in two forms is
604
+ * placed twice and a caller that placed only one of them has the other
605
+ * reported rather than carried along with it: a page can be published in a
606
+ * second form while its first form stands unchanged, which is the distinction
607
+ * `formsGained` exists for.
608
+ *
609
+ * The first placing of a form wins and the second is ignored, as in
610
+ * {@link treesIn}: two answers disagree about one page, nothing here can say
611
+ * which is right, and a silent last-wins would make the libraries depend on the
612
+ * order a caller's history came back in.
613
+ */
614
+ export declare const placingsIn: (placed: Iterable<PlacedForm>) => FormPlacings;
615
+ /** The two libraries a window holds, as the four library comparisons take them. */
616
+ export type WindowLibraries = {
617
+ /** The deployment's pages at the revisions the window opened on. */
618
+ readonly was: LibraryWindow;
619
+ /** The same pages at the revisions it closed on. */
620
+ readonly now: LibraryWindow;
621
+ /**
622
+ * Forms held at one revision that the placings could not place, in a stable
623
+ * order.
624
+ *
625
+ * On neither side, because a side is the assertion: putting an unplaceable
626
+ * form on the later one publishes a page nobody touched as a page gained
627
+ * (0295), and putting it on both publishes a page that was published this
628
+ * week as a page that was always there. It is reported for the reason
629
+ * {@link UnjoinedRevision} and {@link WindowPairs.unpaired} are — a screen
630
+ * that silently left it out would show a deployment fewer pages than it has
631
+ * — and a caller that can place it calls again with a source that does.
632
+ */
633
+ readonly unplaced: readonly UnpairedForm[];
634
+ /**
635
+ * Forms named more than once across `pairs` and `unpaired`, dropped after the
636
+ * first.
637
+ *
638
+ * Nought for anything {@link windowPairsOf} produced, which files each form
639
+ * in exactly one of the two lists. It is not nought for a caller that
640
+ * assembled a {@link WindowPairs} of its own or concatenated two, and the
641
+ * repeat has to be dropped here rather than carried: two readings of one form
642
+ * on one side are `ambiguous` to `pairedWindowOf`, which takes the page out of
643
+ * every figure in the comparison — so the page would vanish out of a total
644
+ * that went on looking right (0158). The pair wins over the unpaired form,
645
+ * because it is the same form with a revision more.
646
+ */
647
+ readonly duplicated: number;
648
+ };
649
+ /**
650
+ * Assemble a window's pairs into the two libraries the library comparisons
651
+ * take.
652
+ *
653
+ * The third step of this rung, and the one {@link windowPairsOf} named as a gap
654
+ * the day it was built. Five of the nine comparisons take two **readings**, and
655
+ * a pair is one of those; the four library comparisons take two whole
656
+ * **libraries** — every page as it stood before against every page as it stands
657
+ * now — and a window holds both of those too, but not by any arrangement of its
658
+ * pairs alone.
659
+ *
660
+ * After this, every one of the nine is one call off a window:
661
+ *
662
+ * ```ts
663
+ * const { pages } = windowReadingsOf(window, treesIn(trees), registry)
664
+ * const held = windowPairsOf(pages)
665
+ * const { was, now } = windowLibrariesOf(held, window.pageViews, placingsIn(history))
666
+ *
667
+ * const kinds = libraryChangeOf(was.readings, now.readings)
668
+ * const reach = libraryReachChangeOf(was, now)
669
+ * ```
670
+ *
671
+ * ## The one line that composes and is wrong
672
+ *
673
+ * ```ts
674
+ * libraryChangeOf(pairs.map(({ was }) => was), pairs.map(({ now }) => now))
675
+ * ```
676
+ *
677
+ * That type-checks, it runs, and the result does not say what it left out. It
678
+ * drops every form in {@link WindowPairs.unpaired} — which is exactly where **a
679
+ * page published inside the window** lands, because a page published inside the
680
+ * window has one revision in it. So a deployment that published two pages this
681
+ * week reads `pagesGained: 0`, which is the figure `libraryChangeOf` exists to
682
+ * report, beside a `pages` count that looks right.
683
+ *
684
+ * ## So the placing is asked for, and a form nobody can place is named
685
+ *
686
+ * A form with one revision is a page published, a page withdrawn, or a page
687
+ * nobody touched, and the counters cannot tell them apart —
688
+ * `StoredTally.updatedAt` is when the fold ran, not when the page went up. The
689
+ * revision numbers cannot either: a revision number is a count of revisions
690
+ * rather than a date, and a deployment that has pruned old counters has a form
691
+ * at revision 7 with nothing below it.
692
+ *
693
+ * So {@link FormPlacings} is handed in, which is the line §7 draws and the
694
+ * shape the region floor took: hold configuration you were handed rather than
695
+ * configuration you went looking for. A form the source cannot place is in
696
+ * {@link WindowLibraries.unplaced} and on neither side, because **both guesses
697
+ * are assertions** — the later side says a page nobody touched was published,
698
+ * and both sides say a page published this week was always there.
699
+ *
700
+ * Paired forms are never asked about. A form with two revisions in the window
701
+ * has its earlier revision in the earlier library and its later one in the
702
+ * later library, by construction, so there is nothing for a caller to answer
703
+ * and nothing of its answer to ignore.
704
+ *
705
+ * ## Two generations of revisions, which is not two moments
706
+ *
707
+ * The sides are the library at its earlier revisions against the library at its
708
+ * later ones, and `republished` on the comparison is the published count of how
709
+ * many pages that moved. It is **not** a window split in half: an `unchanged`
710
+ * form carries one reading onto both sides, so its views are the window's views
711
+ * on both — the page contributed no change because it was not changed, and
712
+ * `LibraryChange.viewsWas` and `viewsNow` are the floors a reader checks the
713
+ * comparability of two windows against rather than numbers to subtract.
714
+ *
715
+ * One consequence worth stating, because it is a limit rather than a rule: a
716
+ * page published **and** then revised inside one window has two revisions, so it
717
+ * is paired and lands on both sides rather than being counted as a page gained.
718
+ * `pagesGained` is therefore a count of the forms whose only revision is new.
719
+ *
720
+ * ## The rows are the window's own, and both sides read them
721
+ *
722
+ * {@link LibraryWindow.rows} is the whole window of door rows on each side, not
723
+ * a slice of them. Each page's own row is picked out by `pageViewsFor` on the
724
+ * revision and the form the reading names (0290), and the two sides name
725
+ * different revisions, so one array answers both without either side borrowing
726
+ * the other's arrivals.
727
+ *
728
+ * ## It adds no figure of its own
729
+ *
730
+ * Nothing here counts, divides, sums or withholds, which is the rule the first
731
+ * two steps set. It decides **which library each form is in** out of what it was
732
+ * told, and hands each side the readings it holds.
733
+ *
734
+ * Linear in the forms, but for the two sorts that publish them in one order.
735
+ */
736
+ export declare const windowLibrariesOf: (held: WindowPairs, rows: readonly StoredPageViews[], placings: FormPlacings) => WindowLibraries;
737
+ /**
738
+ * The configuration a deployment hands a reading of its own window.
739
+ *
740
+ * Four facts, in one value. Two of them have been held rather than looked for
741
+ * since this rung began — the trees the counters were filed against and the
742
+ * registry's declarations (0309) — and two arrived with the steps that needed
743
+ * them: the floor under a published region bucket, and where a form the window
744
+ * holds one revision of belongs (0319).
745
+ *
746
+ * All four are the deployment's and none of them is discoverable from a counter
747
+ * row, which is the line §7 of the plan draws and the reason this is a type
748
+ * rather than four parameters. What it closes is the one way that line could be
749
+ * crossed by accident: **a caller could leave the floor out.**
750
+ *
751
+ * `regionFloorOf` is raise-only, so an absent floor is the smallest bucket this
752
+ * runtime will ever name — `DEFAULT_REGION_FLOOR` — and a deployment that
753
+ * raised its floor to a hundred had a reading publish buckets of twenty-five
754
+ * about real people, because the argument was optional and nothing in the types
755
+ * said whose it was. The omission fails in the unsafe direction, silently, and
756
+ * is indistinguishable in a diff from a caller that meant the default. Here the
757
+ * floor is required, so passing the default is a sentence a reviewer can read
758
+ * rather than a space where a number is not.
759
+ *
760
+ * **The floor is about the rows there are and not about the switch as it
761
+ * stands.** A notice is handed a floor only where a deployment is reading a
762
+ * region at all (0313), because a notice describes what is collected now. A
763
+ * reading is of rows already collected: a deployment that switched regions off
764
+ * yesterday still holds last week's buckets, and reading those at the minimum
765
+ * because nothing is being counted today would publish exactly what the floor
766
+ * exists to prevent.
767
+ */
768
+ export type DeploymentReadingContext = {
769
+ /** The trees the window's revisions were filed against, as the caller holds them. */
770
+ readonly trees: RevisionTrees;
771
+ /** What each primitive declares it plays and says, from the registry (0114, 0122). */
772
+ readonly declarations: PartDeclarations;
773
+ /**
774
+ * The smallest region bucket this deployment will name, in page views.
775
+ *
776
+ * Required, and `regionFloorOf` still raises anything below the runtime's own
777
+ * minimum: a deployment may be more careful than the default and may not be
778
+ * less (0146). A caller with nothing of its own to say passes
779
+ * `DEFAULT_REGION_FLOOR` and has said so.
780
+ */
781
+ readonly floor: number;
782
+ /**
783
+ * Where a form the window holds one revision of belongs (0319).
784
+ *
785
+ * A caller that cannot place any of them hands in `placingsIn([])`, which
786
+ * reports every such form in {@link WindowLibraries.unplaced} rather than
787
+ * guessing it onto a side. That is the honest shape of *this deployment does
788
+ * not know what it published when*, and it is one call rather than an
789
+ * argument left out.
790
+ */
791
+ readonly placings: FormPlacings;
792
+ };
793
+ /** Everything a window holds, as the readings and the comparisons take it. */
794
+ export type WindowAssembly = {
795
+ /** One reading per page, per revision, per form, with the regions beside them. */
796
+ readonly readings: WindowReadings;
797
+ /** The before-and-afters, which is what five of the nine comparisons take. */
798
+ readonly pairs: WindowPairs;
799
+ /** The two libraries, which is what the other four take. */
800
+ readonly libraries: WindowLibraries;
801
+ };
802
+ /**
803
+ * Assemble a window into every subject a reading or a comparison of it takes.
804
+ *
805
+ * The fourth step of this rung and the one that makes the first three a
806
+ * question rather than a recipe. Each of them is published and each is
807
+ * separately useful; what is published nowhere is **the one order they compose
808
+ * in**, and that order is not free.
809
+ *
810
+ * ```ts
811
+ * const { readings, pairs, libraries } = windowAssemblyOf(window, context)
812
+ *
813
+ * const order = deploymentChangeOf(
814
+ * pairs.pairs.map(({ was, now }) => readingChangeOf(was, now)),
815
+ * window.pageViews
816
+ * )
817
+ * const kinds = libraryChangeOf(libraries.was.readings, libraries.now.readings)
818
+ * ```
819
+ *
820
+ * ## What a caller writing those three lines had to get right
821
+ *
822
+ * **The libraries take the pairs that `windowPairsOf` produced**, and the
823
+ * tempting one-liner over `pairs` alone drops every unpaired form — which is
824
+ * where a page published inside the window lands, and `pagesGained` is the
825
+ * figure a library comparison exists to report (0319). **The door rows are the
826
+ * window's whole set on both sides**, not a slice per side, because each page's
827
+ * own row is picked out on the revision and the form its reading names. **And
828
+ * the floor reaches the regions through the readings**, which is the one of the
829
+ * four context fields with no step of its own to be handed to.
830
+ *
831
+ * None of those is hard. All of them are invisible when wrong: the result of
832
+ * getting any of them wrong is a figure that is plausible and a total that goes
833
+ * on looking right, which is the one error in this subsystem that cannot be
834
+ * undone afterwards (0158).
835
+ *
836
+ * ## The two repeats it cannot have, which is the only safety it adds
837
+ *
838
+ * `WindowPairs.duplicated` and `WindowLibraries.duplicated` are **nought from
839
+ * here, by construction.** `windowReadingsOf` never produces two readings of
840
+ * one `readingKeyOf`, and `windowPairsOf` files each form in exactly one of its
841
+ * two lists — so nothing this hands on can put two readings of one form on one
842
+ * side of a library, which is the repeat that makes a page `ambiguous` to
843
+ * `pairedWindowOf` and takes it out of every figure in the comparison while the
844
+ * counts above it look unchanged.
845
+ *
846
+ * Both fields stay published and are carried as they come, because they are not
847
+ * nought for the callers they exist for: a surface that concatenated two
848
+ * windows' readings, or assembled a {@link WindowPairs} of its own, still has
849
+ * them counted. {@link WindowRegionReadings.duplicated} is the one that can be
850
+ * other than nought from here, because a region row repeated under one bucket
851
+ * key is a repeat in the rows a caller was handed rather than one this made.
852
+ *
853
+ * ## It adds no figure, and publishes no total of what was dropped
854
+ *
855
+ * Nothing here counts, divides, sums or withholds — the rule all three steps
856
+ * under it keep. In particular there is deliberately **no one number for what
857
+ * the assembly left out**: the three `duplicated` counts are a count of region
858
+ * rows, a count of readings and a count of forms, and `unjoined`, `unpaired`
859
+ * and `unplaced` are three different reasons a page is absent from three
860
+ * different answers. A sum over them would be a figure in no unit at all, and
861
+ * the shortest way to a screen that reports *4 pages dropped* about one page.
862
+ *
863
+ * Linear in the window, being three linear passes over it.
864
+ */
865
+ export declare const windowAssemblyOf: (window: ReaderWindow, context: DeploymentReadingContext) => WindowAssembly;
866
+ //# sourceMappingURL=window.d.ts.map