@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,309 @@
1
+ import type { NodeId, TreeId } from "../ids.js";
2
+ import type { PrimitiveType } from "../primitive-type.js";
3
+ import type { PrimitiveRole } from "../role.js";
4
+ import { type StoredPageViews } from "./page-views.js";
5
+ import type { PageReading, PartStanding } from "./parts.js";
6
+ /**
7
+ * How far into a page readers get, as a share of the readers there were.
8
+ *
9
+ * Every figure a reader screen will show is a rate, and this subsystem has
10
+ * carried its numerator and its denominator in two places that never met. A
11
+ * part's `reached` is distinct page views that saw it, added across rollup
12
+ * windows, so a visit that straddled a boundary is counted twice and nobody
13
+ * could say how often that happened. A page's openings are counted once at the
14
+ * door, are exact, and add across windows, revisions and months. A reading
15
+ * joined the first to the tree and used the largest row it could find as a
16
+ * floor on how many readers there were; the exact number was one row away and
17
+ * nothing fetched it.
18
+ *
19
+ * **This is that join, and what it buys is an honest rate where there was a
20
+ * count nobody could qualify.** *About two hundred of the three hundred and
21
+ * twenty readers who arrived got as far as the pricing band* is the sentence,
22
+ * and the arithmetic that makes it sayable is a division nobody had to collect
23
+ * anything for: it is the fifth thing taken out of the server-side join rather
24
+ * than off the wire. Nothing is added to a payload, a browser, a column, a
25
+ * store or the vocabulary.
26
+ *
27
+ * ## Two denominators, because they fail in opposite directions
28
+ *
29
+ * `appearances` is the same page views as the rollups counted them — once per
30
+ * window each appeared in — so it carries the straddle over-count that a
31
+ * part's `reached` carries, and dividing one by the other very nearly cancels
32
+ * it. That is the argument the fall between two siblings is built on
33
+ * ([0221](../../decisions/0221-where-reading-stops-is-a-fall-between-two-siblings-and-a-ratio-of-two-counts-off-one-row-set.md)),
34
+ * one level up: a part against its page rather than a part against its
35
+ * neighbour.
36
+ *
37
+ * `opened` is exact, and dividing by it gives something stronger than an
38
+ * estimate and narrower in use: a **ceiling**. A part's `reached` is at least
39
+ * the number of readers who really reached it, and the openings are a count of
40
+ * readers that cannot be inflated by a window boundary, so the true share
41
+ * cannot be above `reached ÷ opened`. The ratio can honestly sit above 1 —
42
+ * which is why it is not the figure a stop is reported as — and when it does,
43
+ * the ceiling says nothing and the fact that it says nothing is itself the
44
+ * answer.
45
+ *
46
+ * **The gap between the estimate and the ceiling is the straddle**, which is
47
+ * the measurement
48
+ * [0219](../../decisions/0219-a-page-view-is-counted-once-at-the-door-and-the-over-count-in-the-node-counters-is-a-measurement.md)
49
+ * published and nothing had used yet. It closes to nothing on a deployment
50
+ * whose rollup window is long enough that nobody's visit spans two — and that
51
+ * is the first time the one control a deployment has over this error can be
52
+ * checked against a number after it is turned.
53
+ *
54
+ * ## What it refuses to say
55
+ *
56
+ * A share of readers is three divisions away from a profile of one, so the
57
+ * things not here are worth naming. There is no page-level total of the
58
+ * readers who got anywhere: one reader who reached four bands is in four rows,
59
+ * and adding them counts them four times. There is no ranking, because where a
60
+ * page loses readers is a question about two siblings and is answered
61
+ * elsewhere. And a projection onto the exact denominator is withheld whenever
62
+ * the collection is behind, because applying the rate of the page views that
63
+ * have been folded to the page views that have not is a guess about readers
64
+ * nobody has counted yet.
65
+ *
66
+ * Pure. It is handed a reading and the page-view rows, and reaches no store, no
67
+ * clock and no DOM; it adds nothing to the broadcaster's import graph.
68
+ */
69
+ /**
70
+ * Why a share of readers cannot be given at all.
71
+ *
72
+ * Each one is a state of the deployment rather than of the page, so it is
73
+ * reported once for the reading instead of on every part — and each is a
74
+ * different sentence, which is the reason there are three rather than a null.
75
+ */
76
+ export type ReachSilence =
77
+ /**
78
+ * No page-view row for this tree and revision.
79
+ *
80
+ * Either the counter has never been written for it — a deployment whose
81
+ * intake predates the column, or one whose rows have expired — or the caller
82
+ * read the rows for something else. The counters are still a floor on how
83
+ * many readers there were, which is what a reading reported before this
84
+ * join existed, so a surface has something to fall back to and should say
85
+ * which it is showing.
86
+ */
87
+ "unmeasured"
88
+ /**
89
+ * The row is there and nothing in it says a page view ever began.
90
+ *
91
+ * Two deployments look like this and the second is the one worth catching.
92
+ * If no rollup has counted an appearance either, nobody has read this
93
+ * revision and there is nothing to divide. If appearances have been counted,
94
+ * **the senders are not marking their openings** — a page running a
95
+ * broadcaster from before the marker shipped, or one whose opening delivery
96
+ * is being lost — and every rate on the screen has no denominator while the
97
+ * counters look healthy. That is a diagnosis nothing else in this subsystem
98
+ * offers.
99
+ */
100
+ | "unopened"
101
+ /**
102
+ * Readers arrived and no rollup has folded a window yet.
103
+ *
104
+ * Everything is `pending`. It is what the first minutes of a deployment look
105
+ * like, and what a stalled collection looks like for ever, and the two are
106
+ * told apart by whether the number moves.
107
+ */
108
+ | "uncounted";
109
+ export declare const REACH_SILENCES: readonly ReachSilence[];
110
+ /** One line per silence, for a surface putting the reading in front of a person. */
111
+ export declare const describeReachSilence: (silence: ReachSilence) => string;
112
+ /**
113
+ * How far one part of a page got, against the readers there were.
114
+ *
115
+ * The identity and the standing are carried over from the reading rather than
116
+ * re-derived, so a surface drawing this never has to hold two lists side by
117
+ * side and match them up by id.
118
+ */
119
+ export type PartReach = {
120
+ readonly nodeId: NodeId;
121
+ readonly type: PrimitiveType;
122
+ /** What part it plays, or `null` where its type declared none (0114). */
123
+ readonly role: PrimitiveRole | null;
124
+ /** 0 at the root, as the reading's outline gives it. */
125
+ readonly depth: number;
126
+ readonly standing: PartStanding;
127
+ /**
128
+ * Distinct page views that saw it, exactly as stored: added across rollup
129
+ * windows and therefore generous (0147).
130
+ *
131
+ * Published beside the shares rather than hidden behind them, because it is
132
+ * the only figure here that is not a division and the one to fall back to
133
+ * when the pair cannot be reconciled.
134
+ */
135
+ readonly reached: number;
136
+ /**
137
+ * The share of page views that got this far, as the rollups counted both
138
+ * ends: `reached ÷ appearances`.
139
+ *
140
+ * The straddle over-count is in the numerator and the denominator and very
141
+ * nearly divides out, which is what makes this the figure to show. It is an
142
+ * estimate and not a bound, and the direction it leans is worth knowing: a
143
+ * reader who stayed long enough to span two windows is counted twice on both
144
+ * sides, and a reader who stays longer is likelier to have got deep into the
145
+ * page — so for a part near the bottom this reads a little generous.
146
+ *
147
+ * **Its denominator is the page views that have been counted, which is not
148
+ * every reader who arrived.** While openings are pending the two are
149
+ * different populations, so this can sit above
150
+ * {@link PartReach.atMost} — that is not a contradiction and the pending
151
+ * figure is the explanation.
152
+ *
153
+ * `null` under a silence.
154
+ */
155
+ readonly share: number | null;
156
+ /**
157
+ * The most the share could be: `reached ÷ opened`, never above 1.
158
+ *
159
+ * A ceiling rather than an estimate. The openings are a count of readers that
160
+ * no window boundary can inflate, and `reached` is at least the number of
161
+ * readers who really got here, so the true share is at or below this.
162
+ *
163
+ * **For a part nearly everybody reaches it is 1 and says nothing**, and that
164
+ * is the ordinary state rather than a fault: a root is in the viewport of
165
+ * every page view, so where any visit spanned two windows its `reached` is
166
+ * above the openings on its own. The estimate is the figure with information
167
+ * in it there; this is the one that bounds a part further down.
168
+ *
169
+ * `null` under a silence.
170
+ */
171
+ readonly atMost: number | null;
172
+ /**
173
+ * The share applied to the exact count of readers who arrived — the number a
174
+ * sentence can say out loud.
175
+ *
176
+ * Deliberately not rounded: it is a magnitude and not a census, and a surface
177
+ * that rounds it is saying how precise it thinks it is.
178
+ *
179
+ * **One division of two whole numbers, not the share multiplied back up.**
180
+ * The two are the same arithmetic in exact numbers and not in a float —
181
+ * seven readers out of a hundred, times a hundred, is seven and a
182
+ * quadrillionth, which is above the most readers who could have got there and
183
+ * would make this figure break its own ceiling.
184
+ *
185
+ * Withheld in three states rather than given as a number nobody could stand
186
+ * behind: under a silence; whenever the collection is behind, because
187
+ * openings a rollup has not reached yet are readers whose reading nobody has
188
+ * counted and projecting the folded rate onto them would answer a question
189
+ * about people who were never measured; and where the two counters cannot be
190
+ * reconciled, because a count of people above the number of people who
191
+ * arrived is the one figure a screen must never show.
192
+ */
193
+ readonly readers: number | null;
194
+ /**
195
+ * The most readers who could have got here: the smaller of `reached` and the
196
+ * openings, which is a whole number of real page views either way.
197
+ *
198
+ * `null` under a silence. Where {@link PartReach.readers} is given it is
199
+ * never above this.
200
+ */
201
+ readonly atMostReaders: number | null;
202
+ /**
203
+ * More reach than there were page views to be reached in, so the share sits
204
+ * above 1 and no figure here can be drawn.
205
+ *
206
+ * Reach is counted out of the same windows as the appearances it is divided
207
+ * by, and a view that reached a part in a window is a view that appeared in
208
+ * it — so rows written by the same rollups cannot produce this. Two things
209
+ * can. **Node counters older than the page-view column**, added up over
210
+ * windows whose appearances were never kept, which is what an upgraded
211
+ * deployment's first reading looks like. Or a caller who concatenated two
212
+ * reads of the counters instead of letting the store add them, which the
213
+ * reading upstream reports as a duplicated node.
214
+ *
215
+ * It is not the ordinary straddle: `reached` above the *openings* is
216
+ * expected, and is what {@link PartReach.atMost} being 1 means.
217
+ *
218
+ * A surface should show `reached` and say it cannot yet be put as a share.
219
+ */
220
+ readonly unreconciled: boolean;
221
+ };
222
+ /**
223
+ * A window of counters, read against the exact number of readers that window
224
+ * had.
225
+ *
226
+ * The page-view figures are the ones a reading of that counter alone would
227
+ * give, carried here so that a surface drawing shares has the arithmetic behind
228
+ * them on the same object and does not have to pair two readings up by hand.
229
+ */
230
+ export type PageReach = {
231
+ readonly treeId: TreeId;
232
+ readonly revision: number;
233
+ /** Page views that began on this revision. Exact, and addable (0219). */
234
+ readonly opened: number;
235
+ /** The same page views as the rollups counted them: once per window each appeared in. */
236
+ readonly appearances: number;
237
+ /** Appearances in excess of openings — the straddle, measured. Never negative. */
238
+ readonly drift: number;
239
+ /** Openings whose reading no rollup has folded yet. The other sign of the same subtraction. */
240
+ readonly pending: number;
241
+ /** `drift ÷ opened`: how generous every distinct count here is. `null` when nothing opened. */
242
+ readonly inflation: number | null;
243
+ /** When the page-view row last moved, or `null` where there is no row. */
244
+ readonly updatedAt: string | null;
245
+ /**
246
+ * The floor the counters give on their own: the largest `views` any one row
247
+ * reports.
248
+ *
249
+ * What a reading had to use as a denominator before there was an exact one,
250
+ * kept so that a deployment can see the difference the join made rather than
251
+ * being told it was wrong. Against an honest sender it sits at or below the
252
+ * openings plus the straddle.
253
+ */
254
+ readonly countedViews: number;
255
+ /**
256
+ * Set where no share can be given, and the reason. `null` where they can.
257
+ */
258
+ readonly silence: ReachSilence | null;
259
+ /**
260
+ * Nobody's visit spanned two windows, so there is nothing to divide out: the
261
+ * estimate and the ceiling are the same number and the shares are exact.
262
+ *
263
+ * False under a silence, and false while any opening is pending.
264
+ */
265
+ readonly exact: boolean;
266
+ /** Every part of the revision, in reading order, as the reading had them. */
267
+ readonly parts: readonly PartReach[];
268
+ /**
269
+ * The parts whose reach could not be reconciled with the openings.
270
+ *
271
+ * Empty is the healthy state. A non-empty list on a deployment whose drift is
272
+ * nought is not a straddle and not a lie: it is node counters older than the
273
+ * column they are being divided by.
274
+ */
275
+ readonly unreconciled: readonly NodeId[];
276
+ /**
277
+ * Page-view rows handed in for another tree or another revision, and ignored.
278
+ *
279
+ * Dividing one revision's counters by another's readers is the mistake that
280
+ * would make every rate here quietly wrong, so this filters rather than
281
+ * trusts its caller — and says how much it dropped, because a caller who
282
+ * passed a whole store's rows and one who passed the wrong revision's look
283
+ * identical from the inside.
284
+ */
285
+ readonly foreign: number;
286
+ /**
287
+ * Rows for this tree and revision beyond the first, where every one after it
288
+ * was ignored.
289
+ *
290
+ * A store keeps one row per revision, so this cannot happen from one read —
291
+ * it happens when a caller concatenates two reads. Adding them is wrong,
292
+ * because the openings are already a total and would double; taking the last
293
+ * is wrong, because it is not the truer one. So the first row stands and the
294
+ * fact is reported.
295
+ */
296
+ readonly duplicated: number;
297
+ };
298
+ /**
299
+ * Read a window's counters against the readers that window had.
300
+ *
301
+ * The reading names the tree and the revision it was built for, so the rows are
302
+ * filtered to it here rather than being trusted: there is no way to ask this
303
+ * question about a revision without holding the revision, which is the property
304
+ * the join upstream has and this one keeps.
305
+ *
306
+ * Linear in the parts and in the rows, with one pass over each.
307
+ */
308
+ export declare const pageReachOf: (reading: PageReading, rows: readonly StoredPageViews[]) => PageReach;
309
+ //# sourceMappingURL=reach.d.ts.map
@@ -0,0 +1,93 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { pageViewsFor } from "./page-views.js";
3
+ export const REACH_SILENCES = everyMemberOf()([
4
+ "unmeasured",
5
+ "unopened",
6
+ "uncounted",
7
+ ]);
8
+ /** One line per silence, for a surface putting the reading in front of a person. */
9
+ export const describeReachSilence = (silence) => {
10
+ switch (silence) {
11
+ case "unmeasured":
12
+ return "no page views have been counted for this version of the page";
13
+ case "unopened":
14
+ return "nothing has said a page view began, so there is no number to divide by";
15
+ case "uncounted":
16
+ return "readers have arrived and no window of their reading has been counted yet";
17
+ }
18
+ };
19
+ const NOTHING_MEASURED = {
20
+ opened: 0,
21
+ appearances: 0,
22
+ drift: 0,
23
+ pending: 0,
24
+ inflation: null,
25
+ updatedAt: null,
26
+ };
27
+ const silenceOf = (opened, appearances) => {
28
+ if (opened === 0)
29
+ return "unopened";
30
+ if (appearances === 0)
31
+ return "uncounted";
32
+ return null;
33
+ };
34
+ /**
35
+ * Read a window's counters against the readers that window had.
36
+ *
37
+ * The reading names the tree and the revision it was built for, so the rows are
38
+ * filtered to it here rather than being trusted: there is no way to ask this
39
+ * question about a revision without holding the revision, which is the property
40
+ * the join upstream has and this one keeps.
41
+ *
42
+ * Linear in the parts and in the rows, with one pass over each.
43
+ */
44
+ export const pageReachOf = (reading, rows) => {
45
+ /**
46
+ * The row this revision's counters are divided by, picked by the one rule
47
+ * that knows which row belongs to which reading (`pageViewsFor`). The rule is
48
+ * shared rather than written here because it is also what a consumer of the
49
+ * pace reading needs, and the matching is the part of this join that fails
50
+ * quietly when it is got wrong.
51
+ */
52
+ const { measured, foreign, duplicated } = pageViewsFor(reading, rows);
53
+ const { opened, appearances, drift, pending, inflation, updatedAt } = measured ?? NOTHING_MEASURED;
54
+ const silence = measured === null ? "unmeasured" : silenceOf(opened, appearances);
55
+ const exact = silence === null && appearances === opened;
56
+ const parts = reading.parts.map((part) => {
57
+ const reached = part.counters?.reached ?? 0;
58
+ const unreconciled = silence === null && reached > appearances;
59
+ const share = silence === null ? reached / appearances : null;
60
+ const atMost = silence === null ? Math.min(1, reached / opened) : null;
61
+ return {
62
+ nodeId: part.nodeId,
63
+ type: part.type,
64
+ role: part.role,
65
+ depth: part.depth,
66
+ standing: part.standing,
67
+ reached,
68
+ share,
69
+ atMost,
70
+ readers: share === null || pending > 0 || unreconciled ? null : (reached * opened) / appearances,
71
+ atMostReaders: silence === null ? Math.min(reached, opened) : null,
72
+ unreconciled,
73
+ };
74
+ });
75
+ return {
76
+ treeId: reading.treeId,
77
+ revision: reading.revision,
78
+ opened,
79
+ appearances,
80
+ drift,
81
+ pending,
82
+ inflation,
83
+ updatedAt,
84
+ countedViews: reading.views,
85
+ silence,
86
+ exact,
87
+ parts,
88
+ unreconciled: parts.filter((part) => part.unreconciled).map((part) => part.nodeId),
89
+ foreign,
90
+ duplicated,
91
+ };
92
+ };
93
+ //# sourceMappingURL=reach.js.map
@@ -0,0 +1,34 @@
1
+ /**
2
+ * What *on screen* means, as the two numbers that decide it.
3
+ *
4
+ * `viewed` and `dwelled` are the two kinds a browser produces by watching, and
5
+ * what they are watching for is one rule: enough of an element is showing that a
6
+ * reader could be reading it. The rule is applied in `broadcast.ts`, where the
7
+ * intersection observer is; the numbers are here because they are the whole of
8
+ * what those two kinds **mean**, and a page that explains either of them should
9
+ * be able to say so without typing a number beside the noun it counts.
10
+ *
11
+ * They are published for that reason and no other. Nothing configures them: a
12
+ * deployment that could set its own would have counters whose meaning differed
13
+ * from every other deployment's while the column names stayed the same, and
14
+ * changing them at all changes what every counter already stored meant when it
15
+ * was written. They are a documented promise rather than a threshold to tune.
16
+ *
17
+ * **Deliberately not in the broadcaster's own module.** A name that a browser
18
+ * entry point exports survives minification, and two exported names cost every
19
+ * reader of every page about 77 bytes to serve a sentence on a documentation
20
+ * site. Imported into `broadcast.ts` and re-exported from `@jam-overture/loom/signals`
21
+ * instead, the browser pays for the two numbers and not for what they are
22
+ * called (rule 4 of `docs/signals.md`).
23
+ */
24
+ /** At least this much of the element is visible. */
25
+ export declare const READABLE_VISIBLE_FRACTION = 0.5;
26
+ /**
27
+ * Or the element fills at least this much of the window.
28
+ *
29
+ * Not optional and not a softening: the visible fraction of an element taller
30
+ * than the window can never reach {@link READABLE_VISIBLE_FRACTION}, so a long
31
+ * section judged by that clause alone would never be viewed at all.
32
+ */
33
+ export declare const READABLE_VIEWPORT_FRACTION = 0.3;
34
+ //# sourceMappingURL=readable.d.ts.map
@@ -0,0 +1,34 @@
1
+ /**
2
+ * What *on screen* means, as the two numbers that decide it.
3
+ *
4
+ * `viewed` and `dwelled` are the two kinds a browser produces by watching, and
5
+ * what they are watching for is one rule: enough of an element is showing that a
6
+ * reader could be reading it. The rule is applied in `broadcast.ts`, where the
7
+ * intersection observer is; the numbers are here because they are the whole of
8
+ * what those two kinds **mean**, and a page that explains either of them should
9
+ * be able to say so without typing a number beside the noun it counts.
10
+ *
11
+ * They are published for that reason and no other. Nothing configures them: a
12
+ * deployment that could set its own would have counters whose meaning differed
13
+ * from every other deployment's while the column names stayed the same, and
14
+ * changing them at all changes what every counter already stored meant when it
15
+ * was written. They are a documented promise rather than a threshold to tune.
16
+ *
17
+ * **Deliberately not in the broadcaster's own module.** A name that a browser
18
+ * entry point exports survives minification, and two exported names cost every
19
+ * reader of every page about 77 bytes to serve a sentence on a documentation
20
+ * site. Imported into `broadcast.ts` and re-exported from `@jam-overture/loom/signals`
21
+ * instead, the browser pays for the two numbers and not for what they are
22
+ * called (rule 4 of `docs/signals.md`).
23
+ */
24
+ /** At least this much of the element is visible. */
25
+ export const READABLE_VISIBLE_FRACTION = 0.5;
26
+ /**
27
+ * Or the element fills at least this much of the window.
28
+ *
29
+ * Not optional and not a softening: the visible fraction of an element taller
30
+ * than the window can never reach {@link READABLE_VISIBLE_FRACTION}, so a long
31
+ * section judged by that clause alone would never be viewed at all.
32
+ */
33
+ export const READABLE_VIEWPORT_FRACTION = 0.3;
34
+ //# sourceMappingURL=readable.js.map