@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,337 @@
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 PageReading, type PartReading, type PartStanding } from "./parts.js";
5
+ /**
6
+ * How much of what a page says gets read, and which of it nobody saw.
7
+ *
8
+ * The join of step 6 already answers *which parts came into view* and, since
9
+ * [0223](../../decisions/0223-a-prop-is-copy-when-a-reader-could-quote-it.md),
10
+ * holds the words each part says. `wordsReadIn` puts the two together and hands
11
+ * back the text readers reached — which is the right answer to *which copy a
12
+ * reader actually reached* and is not a measurement. A list of strings cannot be
13
+ * put on a screen as a figure, cannot be compared between two windows, and
14
+ * cannot say what is on the other side of it: **the words nobody got to**, which
15
+ * is the half a page is changed because of.
16
+ *
17
+ * This counts both sides. *This page says twelve hundred words, readers reached
18
+ * eleven hundred of them, and the three hundred nobody saw are these.*
19
+ *
20
+ * ## The one figure this module has that the pace reading refuses
21
+ *
22
+ * **A page-wide word total**, which
23
+ * [0230](../../decisions/0230-a-part-was-read-when-readers-had-time-for-its-words-and-only-the-skim-is-a-safe-claim.md)
24
+ * would not have, and the difference is which word count is being added.
25
+ *
26
+ * A part's reading *time* is owed to its subtree — the words on screen while a
27
+ * band was up are the band's and its children's — so those figures nest, a sum
28
+ * charges one reader once per level, and there is deliberately no page total of
29
+ * them anywhere in `pace.ts`. A part's **own** words nest nothing: a text node
30
+ * and a slot node are never parts, every element descendant is a part in its own
31
+ * right, and `PartReading.copy` is therefore a partition of the page's words
32
+ * across its parts exactly once. That is the property 0212 published so that a
33
+ * role row could be added up, and a page total is the same addition one level
34
+ * further.
35
+ *
36
+ * So the two modules are not in disagreement about arithmetic; they are adding
37
+ * two different quantities, one of which partitions and one of which does not.
38
+ * Every figure here is of the partitioning one, which is also why the root needs
39
+ * no special case: it contributes its own words like any other part, rather than
40
+ * containing every part it would outrank.
41
+ *
42
+ * ## What each figure is worth
43
+ *
44
+ * **A share of the words is not a share of the readers.** {@link
45
+ * CopyReading.share} is the share of the words that *at least one* reader
46
+ * reached, because that is what a standing of `read` says (0212). On a page with
47
+ * three hundred readers it will usually be near 1 and it is not a lie: somebody
48
+ * did reach nearly all of it. {@link CopyReading.typical} is the other sentence
49
+ * — the words the average reader got to — and the gap between the two is the
50
+ * point of reporting both.
51
+ *
52
+ * **Both are over the words this window can speak for, and neither is over the
53
+ * page** (0282, 0287). A part whose standing is `unknown` reported something
54
+ * other than coming into view, so a reader plainly had it in front of them and
55
+ * the counter that would say so is missing. Its words are in no term of {@link
56
+ * CopyReading.typical} and in neither term of {@link CopyReading.share}: the
57
+ * denominator of the share is {@link CopyReading.spoken}, published beside it,
58
+ * and the mass outside the question is `wordsByStanding.unknown`. A page where
59
+ * nothing at all reports reach gets `unspoken` and **no figure of either
60
+ * kind**, instead of a nought that reads as *nobody read any of this* beside an
61
+ * `unseen` list that is empty.
62
+ *
63
+ * **The word counts are floors and the floor is reported by standing.** A type
64
+ * that declares no `copy` has words nothing here can see (0122). On the read
65
+ * side that understates the numerator and on the skipped side it understates the
66
+ * denominator, so the direction a share is wrong in depends on where the
67
+ * undeclared parts are — which is exactly why {@link CopyReading.floored} counts
68
+ * them per standing rather than returning one boolean a consumer would have to
69
+ * guess the sign of.
70
+ *
71
+ * Pure, and derived: nothing was added to a payload, a browser, a column, a
72
+ * store or the vocabulary to answer any of this.
73
+ */
74
+ /** One part's own words, with what the window said about the part saying them. */
75
+ export type Passage = {
76
+ readonly nodeId: NodeId;
77
+ readonly type: PrimitiveType;
78
+ /** What part it plays (0114), or `null` where its type declared none. */
79
+ readonly role: PrimitiveRole | null;
80
+ /** 0 at the root. */
81
+ readonly depth: number;
82
+ /** Carried through from the part, so a passage and a part say the same thing. */
83
+ readonly standing: PartStanding;
84
+ /** Distinct page views that reported the part coming into view; `0` where no row named it. */
85
+ readonly readers: number;
86
+ /**
87
+ * The words themselves, in reading order, exactly as the page says them.
88
+ *
89
+ * **Its own, never its subtree's**, so the text of two passages may be
90
+ * concatenated and no sentence is read twice.
91
+ */
92
+ readonly text: readonly string[];
93
+ /** {@link text}, counted. */
94
+ readonly words: number;
95
+ /**
96
+ * Whether this passage is short of words it cannot see.
97
+ *
98
+ * True where the part's type declared no `copy`, or declared a prop holding
99
+ * something that is not a string (0122). The words it does hold are still its
100
+ * own; what is not knowable is whether there are more.
101
+ */
102
+ readonly floored: boolean;
103
+ };
104
+ /** Every part playing one role, with the words they say between them. */
105
+ export type RoleCopy = {
106
+ /** `null` is the row for parts whose type declared no role. */
107
+ readonly role: PrimitiveRole | null;
108
+ /** Parts of this role that say something, which is the rule {@link CopyReading.passages} applies. */
109
+ readonly passages: number;
110
+ readonly words: number;
111
+ /**
112
+ * Words by the standing of the part saying them. The three add to
113
+ * {@link words}.
114
+ */
115
+ readonly wordsByStanding: Readonly<Record<PartStanding, number>>;
116
+ /**
117
+ * This role's words in parts the window can speak for, which is the
118
+ * denominator of {@link share} (0287).
119
+ *
120
+ * Addable across roles, like {@link words} and for the same reason. The rest
121
+ * of the role's words are `wordsByStanding.unknown`, which is the mass
122
+ * outside the question rather than words nobody read.
123
+ */
124
+ readonly spoken: number;
125
+ /**
126
+ * The share of this role's **spoken-for** words at least one reader reached.
127
+ * `null` where the window can speak for none of them (0287).
128
+ *
129
+ * Addable across roles — unlike every view count on a `RoleReading`, which is
130
+ * absent there because distinctness cannot be added (0147). Words can: they
131
+ * are a property of the page rather than of the readers.
132
+ */
133
+ readonly share: number | null;
134
+ /** Passages of this role whose words are a floor. */
135
+ readonly floored: number;
136
+ };
137
+ /** Why there is no typical reader's figure. */
138
+ export type CopySilence =
139
+ /** The page says nothing that could have been read. */
140
+ "wordless"
141
+ /** The window held no views of this revision, so there is no reader to be typical of. */
142
+ | "unmeasured"
143
+ /**
144
+ * Some part's words are a floor, so a mean of them is neither a count nor a
145
+ * ceiling.
146
+ *
147
+ * The share survives a floor and says so; this does not. The numerator is
148
+ * short by the words nobody declared and the denominator is a view floor that
149
+ * is short the other way, so the two errors no longer both lean one way and
150
+ * the figure cannot be published as *at most*.
151
+ */
152
+ | "floored"
153
+ /**
154
+ * No word of the page is in a part this window can speak for, so there is no
155
+ * word to take a mean over.
156
+ *
157
+ * Every passage is `unknown` while the window holds views: rows name the
158
+ * parts and not one of them reports reach (`parts.ts`). A reader who pressed
159
+ * something inside a band no `viewed` ever named plainly had it in front of
160
+ * them, so the words are not words nobody reached — they are words nothing
161
+ * can be said about, and a mean of nought reader-words over them would print
162
+ * *the typical reader reached none of your page* as a measurement (0212).
163
+ *
164
+ * **It is the two figures this withholds and not the standings.** Both the
165
+ * mean and {@link CopyReading.share} are absent, because a share of nought
166
+ * beside an `unseen` list that is empty is the same sentence in a different
167
+ * shape (0287). The words stay in {@link CopyReading.wordsByStanding} under
168
+ * `unknown`, where they can be seen and not acted on, which is the rule
169
+ * {@link CopyReading.unseen} already applies to the same passages.
170
+ */
171
+ | "unspoken"
172
+ /**
173
+ * A part reports more readers than the page has views, which no rollup
174
+ * produces.
175
+ *
176
+ * `reached` counts the views that saw a part and `views` the views that said
177
+ * anything about it, so a row's `reached` can never exceed its own `views` and
178
+ * {@link CopyReading.views} is the largest `views` of any row. A reading where
179
+ * this holds was assembled by hand or by a sender that is not one — the same
180
+ * alarm `PageReading.orphaned` is, at the one other place a figure here would
181
+ * stay plausible while being about nothing.
182
+ */
183
+ | "inconsistent";
184
+ /** The closed set, for a surface that has to account for every reason a figure is absent. */
185
+ export declare const COPY_SILENCES: readonly CopySilence[];
186
+ /** One line per silence, for a surface saying why a figure is not there. */
187
+ export declare const describeCopySilence: (silence: CopySilence) => string;
188
+ /**
189
+ * What one window of one revision says about how much of the page is read.
190
+ *
191
+ * Two shares and a word total, each of which answers a different sentence: how
192
+ * much of the page anybody reached, how much of it the average reader reached,
193
+ * and which passages nobody did.
194
+ */
195
+ export type CopyReading = {
196
+ readonly treeId: TreeId;
197
+ readonly revision: number;
198
+ /** The page's view floor, carried through from the reading unchanged. */
199
+ readonly views: number;
200
+ /**
201
+ * Every word this revision says, counted once.
202
+ *
203
+ * The one page-wide word figure in this subsystem, sound for the one reason
204
+ * the module documentation gives: these are the parts' own words, which
205
+ * partition the page, rather than the subtree words a pace reading nests.
206
+ */
207
+ readonly words: number;
208
+ /** Words by the standing of the part saying them. The three add to {@link words}. */
209
+ readonly wordsByStanding: Readonly<Record<PartStanding, number>>;
210
+ /**
211
+ * The page's words in parts this window can speak for, which is the
212
+ * denominator of {@link share} (0287).
213
+ *
214
+ * Published rather than left to a consumer to subtract, because a surface
215
+ * that works out what a share is of by taking `words` less
216
+ * `wordsByStanding.unknown` is re-deriving the universe the figure is about —
217
+ * which is how two screens come to disagree. The difference is the mass
218
+ * outside the question and is `wordsByStanding.unknown` itself.
219
+ */
220
+ readonly spoken: number;
221
+ /**
222
+ * The share of the words **this window can speak for** that at least one
223
+ * reader reached. `null` where there are none of them (0287).
224
+ *
225
+ * *At least one*, which is what a standing of `read` means and not what a
226
+ * person reads this sentence as. {@link typical} is the per-reader figure.
227
+ *
228
+ * **It is over {@link spoken} and not over {@link words}.** A part whose
229
+ * standing is `unknown` has a `read` of nought that is a missing counter
230
+ * rather than a reader who did not arrive, so a page of them published a
231
+ * share of nought — *none of this page was reached* — beside an {@link
232
+ * unseen} list that is empty, because `unseen` is `skipped` only. The
233
+ * commonest page in that state is one nobody opened. Both figures are now
234
+ * absent there and {@link silence} says which state it is.
235
+ */
236
+ readonly share: number | null;
237
+ /** Every part that says something, in reading order. */
238
+ readonly passages: readonly Passage[];
239
+ /**
240
+ * Parts that say nothing at all, counted rather than listed.
241
+ *
242
+ * A spacer, a rule, a stack that only holds other parts. They are not in
243
+ * {@link passages} because a passage of no words is not one, and they are
244
+ * counted because *a page of two hundred parts, ten of which say anything* is
245
+ * a fact about the page worth having and is otherwise invisible here.
246
+ */
247
+ readonly silent: number;
248
+ /**
249
+ * The passages no reader reached, most words first and then in reading order.
250
+ *
251
+ * **`skipped` only.** A part whose standing is `unknown` reported something
252
+ * other than coming into view, or was in a window with no views at all, and
253
+ * putting its words here would turn *nothing can be said* into *nobody read
254
+ * this* — the one direction a reading of a quiet window must not be wrong in.
255
+ * Those words are in {@link wordsByStanding} under `unknown`, where they can
256
+ * be seen and not acted on.
257
+ *
258
+ * By words rather than by depth or position, for the reason a stop is ranked
259
+ * by the readers it loses (0221): the passage nobody saw that costs the page
260
+ * most is the long one, not the first one.
261
+ */
262
+ readonly unseen: readonly Passage[];
263
+ /** Every role in the vocabulary, then the row for parts that declared none. */
264
+ readonly roles: readonly RoleCopy[];
265
+ /**
266
+ * Passages whose words are a floor, by the standing of the part saying them.
267
+ *
268
+ * The direction every share here is wrong in, handed over rather than
269
+ * summarised. Undeclared words under `read` understate the numerator and the
270
+ * denominator together; under `skipped` they understate the denominator only,
271
+ * so a share reads high. One boolean could not have said which.
272
+ */
273
+ readonly floored: Readonly<Record<PartStanding, number>>;
274
+ /**
275
+ * The words the typical reader reached, at most. `null` where {@link silence}
276
+ * says why not.
277
+ *
278
+ * Every word **this window can speak for**, weighted by the readers who
279
+ * reached the part saying it, over the page's views. Generous in both terms
280
+ * and therefore a ceiling: `reached` is over-counted by the page views that
281
+ * straddled a rollup window (0147), and {@link views} is a floor on the page
282
+ * views there were, so the numerator leans up and the denominator leans down.
283
+ *
284
+ * **A ceiling over what was measured, which is a looser one than it looks**
285
+ * (0282). A passage whose standing is `unknown` is in no term, so the figure
286
+ * is at most the spoken-for words — `wordsByStanding.read` plus
287
+ * `wordsByStanding.skipped` — and not at most {@link words}. The gap is
288
+ * `wordsByStanding.unknown`, published beside it, and a page where the gap is
289
+ * everything has no figure at all rather than a nought.
290
+ *
291
+ * The straddle very nearly divides out, which is the only reason this is worth
292
+ * publishing at all: the same inflation is in every `reached` here and in the
293
+ * view floor they are divided by, so what is left is a correction too small to
294
+ * be the headline. It is the cancellation a fall between two siblings already
295
+ * rests on (0221), taken one level up — a page against its own readers rather
296
+ * than a part against its neighbour.
297
+ *
298
+ * It cannot exceed the spoken-for words, and `inconsistent` is the input that
299
+ * would have made it.
300
+ */
301
+ readonly typical: number | null;
302
+ /**
303
+ * Why a figure is not there, and `null` where both are.
304
+ *
305
+ * **It covers {@link share} as well as {@link typical}, and the two are not
306
+ * absent in the same states.** `wordless`, `unmeasured` and `unspoken`
307
+ * withhold both — there is no word, no reader, or no word this window can
308
+ * speak for. `floored` and `inconsistent` withhold the mean and leave the
309
+ * share standing, because a share survives a floor and says so.
310
+ *
311
+ * So `share === null` holds exactly where this is one of the first three,
312
+ * which the suite pins over the closed set rather than leaving to this
313
+ * sentence.
314
+ */
315
+ readonly silence: CopySilence | null;
316
+ };
317
+ /**
318
+ * The words a part says on its own, and whether it is short of some it cannot see.
319
+ *
320
+ * Published rather than kept private, because the comparison of two windows
321
+ * ([`copy-change.ts`](copy-change.ts)) needs a passage for **every** part and
322
+ * not only for the parts {@link copyReadingOf} kept — a part that said nothing
323
+ * before and says something now is a word the change wrote, and reading that
324
+ * off a filtered list would call the part itself new. Two spellings of this
325
+ * projection that agree today are what the counter keys were before they were
326
+ * published once.
327
+ */
328
+ export declare const passageOf: (part: PartReading) => Passage;
329
+ /**
330
+ * How much of what a page says is getting read.
331
+ *
332
+ * Handed the output of `pageReadingOf`, because the words, the counters and the
333
+ * reading order are joined there already and deriving them a second time is how
334
+ * two screens come to disagree.
335
+ */
336
+ export declare const copyReadingOf: (reading: PageReading) => CopyReading;
337
+ //# sourceMappingURL=copy.d.ts.map
@@ -0,0 +1,211 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { PRIMITIVE_ROLES } from "../role.js";
3
+ import { spokenFor } from "./parts.js";
4
+ import { countWords } from "./words.js";
5
+ /** The closed set, for a surface that has to account for every reason a figure is absent. */
6
+ export const COPY_SILENCES = everyMemberOf()([
7
+ "wordless",
8
+ "unmeasured",
9
+ "floored",
10
+ "unspoken",
11
+ "inconsistent",
12
+ ]);
13
+ /** One line per silence, for a surface saying why a figure is not there. */
14
+ export const describeCopySilence = (silence) => {
15
+ switch (silence) {
16
+ case "wordless":
17
+ return "this revision says nothing that could be read";
18
+ case "unmeasured":
19
+ return "the window held no page views of this revision";
20
+ case "floored":
21
+ return "some part of the page declares no copy, so a mean of its words would not be a ceiling";
22
+ case "unspoken":
23
+ return "no part of the page reports whether it was reached, so there is no word to take a mean over";
24
+ case "inconsistent":
25
+ return "a part reports more readers than the page has views, which no rollup produces";
26
+ }
27
+ };
28
+ /** Zero per standing, which both a word total and a count of floored passages start from. */
29
+ const ZERO_BY_STANDING = Object.freeze({
30
+ read: 0,
31
+ skipped: 0,
32
+ unknown: 0,
33
+ });
34
+ /**
35
+ * The words a part says on its own, and whether it is short of some it cannot see.
36
+ *
37
+ * Published rather than kept private, because the comparison of two windows
38
+ * ([`copy-change.ts`](copy-change.ts)) needs a passage for **every** part and
39
+ * not only for the parts {@link copyReadingOf} kept — a part that said nothing
40
+ * before and says something now is a word the change wrote, and reading that
41
+ * off a filtered list would call the part itself new. Two spellings of this
42
+ * projection that agree today are what the counter keys were before they were
43
+ * published once.
44
+ */
45
+ export const passageOf = (part) => ({
46
+ nodeId: part.nodeId,
47
+ type: part.type,
48
+ role: part.role,
49
+ depth: part.depth,
50
+ standing: part.standing,
51
+ readers: part.counters?.reached ?? 0,
52
+ text: part.copy.words,
53
+ words: countWords(part.copy.words),
54
+ floored: part.copy.unread.length > 0 || part.copy.unspoken.length > 0,
55
+ });
56
+ /**
57
+ * Whether a part is saying anything at all.
58
+ *
59
+ * A floored part with no visible words is kept, because *this part may say
60
+ * something and nothing here can see it* is not the same answer as *this part
61
+ * says nothing*, and the first is the one 0122 exists to keep tellable.
62
+ */
63
+ const saysSomething = (passage) => passage.words > 0 || passage.floored;
64
+ /**
65
+ * The share of the spoken-for words that were read, and `null` where there are
66
+ * none of them (0287).
67
+ *
68
+ * The denominator is never {@link CopyReading.words}: a word nothing can be
69
+ * said about is outside the question rather than in the half of it that went
70
+ * unread.
71
+ */
72
+ const shareOf = (read, spoken) => spoken === 0 ? null : read / spoken;
73
+ /**
74
+ * Every role's row, in one pass over the passages.
75
+ *
76
+ * A pass per role would be a scan of the page per member of the vocabulary,
77
+ * which is the shape rule 4 holds this subsystem to: the vocabulary grows and
78
+ * the page is what it is.
79
+ */
80
+ const roleRowsOf = (passages) => {
81
+ const rows = new Map([...PRIMITIVE_ROLES, null].map((role) => [
82
+ role,
83
+ {
84
+ role,
85
+ passages: 0,
86
+ words: 0,
87
+ wordsByStanding: { ...ZERO_BY_STANDING },
88
+ spoken: 0,
89
+ share: null,
90
+ floored: 0,
91
+ },
92
+ ]));
93
+ for (const passage of passages) {
94
+ const row = rows.get(passage.role);
95
+ /**
96
+ * A role this runtime does not know cannot reach here, since a part's role
97
+ * is only ever a member of the closed vocabulary. Skipped rather than
98
+ * thrown, as in the reading this is built on: a row that does not exist
99
+ * cannot be drawn, and a reading is not worth failing over.
100
+ */
101
+ if (row === undefined)
102
+ continue;
103
+ rows.set(passage.role, {
104
+ ...row,
105
+ passages: row.passages + 1,
106
+ words: row.words + passage.words,
107
+ wordsByStanding: {
108
+ ...row.wordsByStanding,
109
+ [passage.standing]: row.wordsByStanding[passage.standing] + passage.words,
110
+ },
111
+ spoken: row.spoken + (spokenFor(passage.standing) ? passage.words : 0),
112
+ share: null,
113
+ floored: row.floored + (passage.floored ? 1 : 0),
114
+ });
115
+ }
116
+ return [...rows.values()].map((row) => ({
117
+ ...row,
118
+ share: shareOf(row.wordsByStanding.read, row.spoken),
119
+ }));
120
+ };
121
+ /**
122
+ * The more costly of two passages nobody saw, which is the ranking rule spelled
123
+ * once.
124
+ *
125
+ * Descending by words, and the comparison is strict so that equal passages keep
126
+ * the reading order they arrived in rather than the last one winning.
127
+ */
128
+ const byWordsLost = (one, other) => other.words - one.words;
129
+ /**
130
+ * Why there is no mean, in the order a page is in more than one of these.
131
+ *
132
+ * `unspoken` sits above `floored` because the two are not the same kind of gap
133
+ * and only one of them has a remedy that produces a figure. A floor is a
134
+ * declaration a library has not made (0122), and a page where nothing reports
135
+ * reach would still have no mean once every `copy` prop was declared. A
136
+ * deployment told *some part declares no copy* would go and fix that and get
137
+ * the same silence back.
138
+ */
139
+ const silenceOf = (words, views, spoken, floored, inconsistent) => {
140
+ if (words === 0)
141
+ return "wordless";
142
+ if (views === 0)
143
+ return "unmeasured";
144
+ if (inconsistent)
145
+ return "inconsistent";
146
+ if (spoken === 0)
147
+ return "unspoken";
148
+ return floored ? "floored" : null;
149
+ };
150
+ /**
151
+ * How much of what a page says is getting read.
152
+ *
153
+ * Handed the output of `pageReadingOf`, because the words, the counters and the
154
+ * reading order are joined there already and deriving them a second time is how
155
+ * two screens come to disagree.
156
+ */
157
+ export const copyReadingOf = (reading) => {
158
+ const passages = reading.parts.map(passageOf).filter(saysSomething);
159
+ const wordsByStanding = passages.reduce((counted, passage) => ({
160
+ ...counted,
161
+ [passage.standing]: counted[passage.standing] + passage.words,
162
+ }), { ...ZERO_BY_STANDING });
163
+ const floored = passages.reduce((counted, passage) => passage.floored
164
+ ? { ...counted, [passage.standing]: counted[passage.standing] + 1 }
165
+ : counted, { ...ZERO_BY_STANDING });
166
+ const words = wordsByStanding.read + wordsByStanding.skipped + wordsByStanding.unknown;
167
+ /**
168
+ * The words in parts this window can speak for either way, which is what the
169
+ * mean and the share below are both over (0282, 0287).
170
+ *
171
+ * Taken with the published predicate rather than as `read + skipped`, which
172
+ * is the same number today and is the spelling that would go on agreeing
173
+ * with a three-member vocabulary after a fourth standing arrived.
174
+ */
175
+ const spoken = passages.reduce((total, passage) => total + (spokenFor(passage.standing) ? passage.words : 0), 0);
176
+ const silence = silenceOf(words, reading.views, spoken, floored.read + floored.skipped + floored.unknown > 0, passages.some((passage) => passage.readers > reading.views));
177
+ /**
178
+ * Weighted by the readers of the part saying each word, over the page's views.
179
+ * Guarded by the silence rather than by a clamp: a figure held back for a
180
+ * stated reason is a reading somebody can act on, and one quietly cut to fit
181
+ * its own ceiling is not.
182
+ *
183
+ * **It is already over the spoken-for passages and is not filtered to them.**
184
+ * A passage is `unknown` only where its row reports no reach at all
185
+ * (`standingOf`), so its term is `0 x words` and the sum over every passage
186
+ * and the sum over the spoken-for ones are the same number. The comparison of
187
+ * two windows has to filter, because there a passage `unknown` on one side
188
+ * carries a real term on the other (0282).
189
+ */
190
+ const typical = silence === null
191
+ ? passages.reduce((total, passage) => total + passage.readers * passage.words, 0) /
192
+ reading.views
193
+ : null;
194
+ return {
195
+ treeId: reading.treeId,
196
+ revision: reading.revision,
197
+ views: reading.views,
198
+ words,
199
+ wordsByStanding,
200
+ spoken,
201
+ share: shareOf(wordsByStanding.read, spoken),
202
+ passages,
203
+ silent: reading.parts.length - passages.length,
204
+ unseen: passages.filter((passage) => passage.standing === "skipped").sort(byWordsLost),
205
+ roles: roleRowsOf(passages),
206
+ floored,
207
+ typical,
208
+ silence,
209
+ };
210
+ };
211
+ //# sourceMappingURL=copy.js.map
@@ -0,0 +1,46 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { ReaderRegionCount } from "./region.js";
3
+ import type { FunnelAnswer, ReaderTally } from "./rollup.js";
4
+ import type { RevisionViews } from "./page-views.js";
5
+ export declare const pageViewKey: (count: RevisionViews) => string;
6
+ export declare const tallyKey: (tally: ReaderTally) => string;
7
+ export declare const funnelKey: (answer: FunnelAnswer) => string;
8
+ export declare const regionKey: (count: ReaderRegionCount) => string;
9
+ /**
10
+ * The same counter, in one audience (0284).
11
+ *
12
+ * The four keys above identify a counter *within* one audience, which is all a
13
+ * fold in front of the driver needs: `apply` and `count` are handed one
14
+ * audience's rows per call, so two entries sharing a key in one call are the
15
+ * same row however many audiences the window held.
16
+ *
17
+ * A store that keeps its rows across calls needs more than that, and only the
18
+ * memory one does — Postgres has the audience in the primary key, so the
19
+ * database is already holding two audiences apart. This is the memory store's
20
+ * half of that same identity, and it is **here rather than beside it** for the
21
+ * reason the rest of this file is: two spellings of a key that agree today are
22
+ * the shape this subsystem has already been bitten by.
23
+ */
24
+ export declare const inAudience: (audience: AudienceId, key: string) => string;
25
+ /**
26
+ * Rows that name the same counter, added together, in the order they arrived.
27
+ *
28
+ * Stable in two ways that matter: a row's first appearance fixes its position,
29
+ * so a fold never reorders a caller's list, and `add` is handed the standing row
30
+ * first — so a non-additive column written by `add` keeps the same winner as the
31
+ * `excluded.*` the upsert would have applied.
32
+ */
33
+ export declare const foldedBy: <Row>(rows: readonly Row[], key: (row: Row) => string, add: (standing: Row, next: Row) => Row) => readonly Row[];
34
+ /** The two numbers a page-view count carries, which is one. */
35
+ export declare const addPageViewCounts: (standing: RevisionViews, next: RevisionViews) => RevisionViews;
36
+ /**
37
+ * Every counter on a tally, added.
38
+ *
39
+ * `type` is the one column that is not a number, and the later row wins it —
40
+ * which is what `SET type = excluded.type` does and what the memory store's
41
+ * spread does, so the fold does not become a third answer.
42
+ */
43
+ export declare const addTallies: (standing: ReaderTally, next: ReaderTally) => ReaderTally;
44
+ export declare const addFunnelAnswers: (standing: FunnelAnswer, next: FunnelAnswer) => FunnelAnswer;
45
+ export declare const addRegionCounts: (standing: ReaderRegionCount, next: ReaderRegionCount) => ReaderRegionCount;
46
+ //# sourceMappingURL=counters.d.ts.map