@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,218 @@
1
+ import { audienceScopeOf, audiencesIn } from "./audiences.js";
2
+ /**
3
+ * The page views a delivery opened, per revision, deduplicated by view key.
4
+ *
5
+ * The dedup inside the delivery is load-bearing rather than defensive: a sender
6
+ * draining a queue after an outage posts what it has, which may include an
7
+ * opening batch it already sent and could not confirm, and a page view counted
8
+ * twice cannot be uncounted
9
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
10
+ * Keys are compared rather than batches, so one opening delivered twice is one
11
+ * page view and two page views opened in one delivery are two.
12
+ *
13
+ * A batch that opened nothing adds nothing, and a sender that never says adds
14
+ * nothing at all — a batch synthesised on a server or replayed from a fixture
15
+ * is not an arrival, exactly as it is not a view (0146). The parser has already
16
+ * refused a batch that claims an opening and names no page view, so a key is
17
+ * always there to compare when the claim is.
18
+ *
19
+ * Pure, and shared: the region counter stamps a country onto these rows rather
20
+ * than walking the delivery itself, which is what keeps the two counters from
21
+ * disagreeing about how many readers arrived.
22
+ */
23
+ export const openingsOf = (batches) => {
24
+ const opened = new Map();
25
+ for (const batch of batches) {
26
+ if (batch.first !== true || batch.view === undefined)
27
+ continue;
28
+ const key = `${batch.treeId} ${batch.revision}`;
29
+ const existing = opened.get(key);
30
+ if (existing === undefined) {
31
+ opened.set(key, {
32
+ treeId: batch.treeId,
33
+ revision: batch.revision,
34
+ views: new Set([batch.view]),
35
+ });
36
+ continue;
37
+ }
38
+ existing.views.add(batch.view);
39
+ }
40
+ return [...opened.values()].map(({ treeId, revision, views }) => ({
41
+ treeId,
42
+ revision,
43
+ views: views.size,
44
+ }));
45
+ };
46
+ const readingOf = (row) => {
47
+ const audiences = audiencesIn([row]);
48
+ return {
49
+ ...row,
50
+ /** One row's own form, and `null` where the row named none (0299). */
51
+ audienceId: audiences[0] ?? null,
52
+ audiences,
53
+ drift: Math.max(0, row.appearances - row.opened),
54
+ pending: Math.max(0, row.opened - row.appearances),
55
+ inflation: row.opened === 0 ? null : Math.max(0, row.appearances - row.opened) / row.opened,
56
+ };
57
+ };
58
+ /**
59
+ * Rows from the store, read as something a screen may show.
60
+ *
61
+ * **Totalled from the rows and never from the totals.** `drift` on the whole
62
+ * reading is the sum of each revision's drift, not the difference of the two
63
+ * sums: a revision mid-collection has openings the rollups have not reached,
64
+ * and subtracting in the aggregate would let that cancel another revision's
65
+ * straddles and report a page as more exact than any part of it is.
66
+ *
67
+ * Unlike a region reading this withholds nothing, groups nothing, and hides
68
+ * nothing. Every row is already an aggregate about a revision of a tree.
69
+ */
70
+ export const pageViewReadingOf = (rows) => {
71
+ const revisions = rows
72
+ .map(readingOf)
73
+ .sort((one, other) => one.treeId.localeCompare(other.treeId) || other.revision - one.revision);
74
+ const total = (of) => revisions.reduce((sum, row) => sum + of(row), 0);
75
+ const opened = total((row) => row.opened);
76
+ const drift = total((row) => row.drift);
77
+ return {
78
+ opened,
79
+ appearances: total((row) => row.appearances),
80
+ drift,
81
+ pending: total((row) => row.pending),
82
+ inflation: opened === 0 ? null : drift / opened,
83
+ revisions,
84
+ };
85
+ };
86
+ /**
87
+ * The newest instant either writer moved one of these rows.
88
+ *
89
+ * A reading's own figure is as fresh as the freshest row under it, so this is a
90
+ * maximum. Compared by parsed instant rather than by string order, because two
91
+ * stores may write the same instant in two spellings and only one of them sorts.
92
+ */
93
+ const movedLast = (rows) => {
94
+ let latest = rows[0]?.updatedAt ?? "";
95
+ for (const row of rows) {
96
+ if (Date.parse(row.updatedAt) > Date.parse(latest))
97
+ latest = row.updatedAt;
98
+ }
99
+ return latest;
100
+ };
101
+ /**
102
+ * The oldest fold attested by one of these rows, or absent where none attests
103
+ * one.
104
+ *
105
+ * A `folded_at` nothing can read attests no fold, which is how a stall reading
106
+ * already treats one (0274): it is skipped rather than kept as the oldest, so
107
+ * one unreadable instant cannot make a deployment's whole collection look
108
+ * unattested.
109
+ */
110
+ const foldWaitedOn = (rows) => {
111
+ let oldest;
112
+ for (const row of rows) {
113
+ const at = row.foldedAt;
114
+ if (at === undefined || Number.isNaN(Date.parse(at)))
115
+ continue;
116
+ if (oldest === undefined || Date.parse(at) < Date.parse(oldest))
117
+ oldest = at;
118
+ }
119
+ return oldest;
120
+ };
121
+ /**
122
+ * One revision's door rows, added into one reading.
123
+ *
124
+ * **The arithmetic is the reading's own, taken over the rows rather than
125
+ * written again.** `opened` and `appearances` are counts and add; `drift` and
126
+ * `pending` are added *per row and never taken from the two sums*, because a
127
+ * form mid-collection has openings no fold has reached and subtracting in the
128
+ * aggregate would let that cancel another form's straddles — which is the rule
129
+ * {@link pageViewReadingOf} already states for revisions and holds for forms of
130
+ * one revision for the same reason; and `inflation` is a ratio, so it is
131
+ * recomputed from the summed drift and the summed openings rather than averaged
132
+ * over the forms. Handing the rows to {@link pageViewReadingOf} is what keeps
133
+ * those four from being a second spelling of one rule.
134
+ */
135
+ const summedOf = (where, audience, rows) => {
136
+ if (rows.length === 0)
137
+ return null;
138
+ const { opened, appearances, drift, pending, inflation } = pageViewReadingOf(rows);
139
+ const waiting = rows.filter((row) => row.opened > row.appearances);
140
+ const folded = foldWaitedOn(waiting.length > 0 ? waiting : rows);
141
+ return {
142
+ treeId: where.treeId,
143
+ revision: where.revision,
144
+ audienceId: audience,
145
+ audiences: audiencesIn(rows),
146
+ opened,
147
+ appearances,
148
+ drift,
149
+ pending,
150
+ inflation,
151
+ updatedAt: movedLast(rows),
152
+ ...(folded === undefined ? {} : { foldedAt: folded }),
153
+ };
154
+ };
155
+ /**
156
+ * Read one revision's door out of a window of rows.
157
+ *
158
+ * Linear in the rows, with one pass and one map.
159
+ */
160
+ export const pageViewsFor = (where, rows) => {
161
+ const here = rows.filter((row) => row.treeId === where.treeId && row.revision === where.revision);
162
+ /**
163
+ * Taken from `audienceScopeOf` rather than spelled here, which is the fourth
164
+ * and last of the readings that pick a page's rows out of a window to read
165
+ * the rule from one place (0300). It was spelled here because this one was
166
+ * being rewritten the same night the rule was published (0299).
167
+ *
168
+ * **The door is the one of the four that answers `mixed` by summing**, and
169
+ * that is why the branch is written out rather than left to fall past a
170
+ * `null`: arrivals are counted once per page view and a reader who arrived
171
+ * arrived once whichever form they were served, so two forms' doors add to
172
+ * one deployment's arrivals (0297, 0299). A page reading and a funnel reading
173
+ * refuse the same window, because a node counter filed under two forms is one
174
+ * number about two pages (0290). Two opposite answers to one case is the
175
+ * reason the case is worth a member.
176
+ */
177
+ const scope = audienceScopeOf(audiencesIn(here), where.audienceId ?? undefined);
178
+ const matching = scope.reading === "mixed" || scope.audienceId === null
179
+ ? here
180
+ : here.filter((row) => row.audienceId === scope.audienceId);
181
+ /**
182
+ * Keyed by the audience, which is what the store keeps one row per (0284):
183
+ * two forms' doors are two rows and one arrival count, and keying them by the
184
+ * revision alone dropped the second as a repeat of the first (0299).
185
+ */
186
+ const first = new Map();
187
+ for (const row of matching) {
188
+ if (!first.has(row.audienceId))
189
+ first.set(row.audienceId, row);
190
+ }
191
+ return {
192
+ /**
193
+ * The audience published is the one the **asking** named and never
194
+ * `scope.audienceId`, which fills a single-membered census in. A window
195
+ * holding one form today is not a reading of one form (0297, 0299), and the
196
+ * scope collapses *asked for* and *the only one there* into one member
197
+ * because the two readings that refuse want them handled alike. This one
198
+ * publishes the field, so it wants them apart.
199
+ */
200
+ measured: summedOf(where, where.audienceId ?? null, [...first.values()]),
201
+ foreign: rows.length - here.length,
202
+ otherAudience: here.length - matching.length,
203
+ duplicated: matching.length - first.size,
204
+ };
205
+ };
206
+ /**
207
+ * The straddle correction for one revision of one page: `drift ÷ opened` off
208
+ * that page's own door — its own form's row where the asking names an audience,
209
+ * and the sum of every form's where it names none (0299).
210
+ *
211
+ * The number `PaceOptions.inflation` wants, published so that a consumer
212
+ * holding a window of counters over several pages does not write the matching
213
+ * itself. `null` where there is no row for the revision, or where nothing has
214
+ * opened — which is *the question has no answer* rather than *the answer is
215
+ * nought*, and is the reason this is not simply `0`.
216
+ */
217
+ export const inflationFor = (where, rows) => pageViewsFor(where, rows).measured?.inflation ?? null;
218
+ //# sourceMappingURL=page-views.js.map
@@ -0,0 +1,344 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { NodeId, TreeId } from "../ids.js";
3
+ import type { PrimitiveType } from "../primitive-type.js";
4
+ import { type PrimitiveRole } from "../role.js";
5
+ import { type CopyDeclarations, type NodeCopy } from "../sdk/copy.js";
6
+ import type { LoomTree } from "../tree/tree.js";
7
+ import { type MaybeAudienceScoped } from "./audiences.js";
8
+ import type { ReaderTally } from "./rollup.js";
9
+ /**
10
+ * What a counter is about, joined on the server from what the page already
11
+ * knows.
12
+ *
13
+ * A batch names a node, a tree and a revision, and nothing else — that is rule 1
14
+ * of [`docs/signals.md`](../../docs/signals.md) and it is not negotiable. The
15
+ * browser therefore has two attributes on an element and no idea that `n_42` is
16
+ * a pricing band, that its primitive declares itself a heading (0114), or which
17
+ * of its props a reader reads (0122).
18
+ *
19
+ * **The server has all three.** Intake and rollup both hold the registry and the
20
+ * tree the batch names, so `dwelled on n_42` becomes *eleven seconds on a
21
+ * pricing band, whose words were these* with no byte added to the payload, no
22
+ * browser change, and no new decision about what to keep.
23
+ * [0167](../../decisions/0167-a-delegated-signal-names-the-regions-it-happened-inside.md)
24
+ * refused ancestry on the high-volume kinds for exactly this reason — payload
25
+ * multiplied by page depth, to buy what the server could derive — and the same
26
+ * argument covers roles, parts and copy.
27
+ *
28
+ * ## The thing only a tree can say
29
+ *
30
+ * Counters answer what happened. They cannot answer what *did not*, because a
31
+ * part nobody reached has no row: absence of a tally is absence of data, and a
32
+ * list of rows can never be read as a list of the page. The tree is the
33
+ * universe — every element node in it is an addressed node, so every one of them
34
+ * is a part a reader could have reached — and against that universe silence
35
+ * becomes a measurement. *Which parts of a page are read and which are scrolled
36
+ * past* is this join and nothing else.
37
+ *
38
+ * ## Why the join is at read time and not at rollup time
39
+ *
40
+ * Rollup also holds the tree and the registry, so it could write the role and
41
+ * the words onto the counters as they are stored. It must not. A declaration is
42
+ * a fact about the library, not about a window of reading: the day
43
+ * `src/primitives/` declares `copy` across itself
44
+ * ([0122](../../decisions/0122-a-primitive-says-which-of-its-props-a-reader-reads.md)
45
+ * says nothing does yet), a read-time join reinterprets every counter already
46
+ * stored, and a rollup-time one has baked the old silence into rows that are
47
+ * expensive to revisit and impossible to correct for windows already expired.
48
+ * The counters stay node-shaped for the same reason the wire does.
49
+ *
50
+ * The tree a reading needs is the one the counters name. For the current
51
+ * revision that is the snapshot a store already holds; for an older one it is
52
+ * `replayTree` over the log, which is how *before versus after a change* reaches
53
+ * two readings.
54
+ *
55
+ * Pure. It is handed a tree, a window's counters and the declarations, and
56
+ * returns a reading; it reaches no store, no clock and no DOM, and it adds
57
+ * nothing to the broadcaster's import graph.
58
+ */
59
+ /**
60
+ * What a window of counters says about one part of a page.
61
+ *
62
+ * Three answers, and the third exists because the other two are claims. A
63
+ * reading that only said *read* or *skipped* would have to call a page nobody
64
+ * opened a page everybody skipped, which is the plausible-false-number failure:
65
+ * a figure that is the right shape, drawn on a screen, and about nothing.
66
+ *
67
+ * **Every combination of the three is reachable except one, and the arithmetic
68
+ * that rules it out is worth having here.** `skipped` means *no row names this
69
+ * part*, and {@link PageReading.views} is the largest `views` any one row
70
+ * reports — both read off the same rows. So every part being `skipped` would
71
+ * need the window to hold no row for any part of the page, which makes `views`
72
+ * zero, which makes every part `unknown` instead. *A page with visits, every
73
+ * part of which went unseen* cannot be drawn from counters, and the one input
74
+ * that produces it is a row naming a node this revision does not have — which is
75
+ * {@link PageReading.orphaned}, and is the one state a consumer should refuse to
76
+ * draw rather than render.
77
+ *
78
+ * The reachable neighbour is the one worth a screen: **rows exist and not one
79
+ * reports reach.** A root is addressed and is in the viewport of every view that
80
+ * draws the page, so that is a page whose parts are not reporting — a primitive
81
+ * not spreading its identity attributes, or a sender switched on halfway through
82
+ * a release — and not a page nobody scrolled. Filed by `Loom portal` on 2 October
83
+ * after a test that tried to build the impossible state and could not.
84
+ */
85
+ export type PartStanding =
86
+ /** At least one view reported it coming into view. */
87
+ "read"
88
+ /**
89
+ * The window held views of this revision, and none of them said anything
90
+ * about this part at all.
91
+ *
92
+ * It was on the page and in nobody's viewport. The one caveat is in the render
93
+ * rather than here: a primitive that does not spread its identity attributes
94
+ * is invisible to the broadcaster and reads as skipped, which is what
95
+ * `sdk/conformance.ts` exists to catch.
96
+ */
97
+ | "skipped"
98
+ /**
99
+ * Nothing can be said.
100
+ *
101
+ * Either the window held no views of this revision — so every part is
102
+ * unknown, and *skipped* would be a statement about readers who were not
103
+ * there — or the part reported something other than coming into view. The
104
+ * second is rarer and sharper: a press was delegated to a band that no
105
+ * `viewed` ever named, so a reader plainly had it in front of them and the
106
+ * counter that would say so is missing. Calling that skipped would be a lie
107
+ * in the direction nobody checks.
108
+ */
109
+ | "unknown";
110
+ export declare const PART_STANDINGS: readonly PartStanding[];
111
+ /**
112
+ * Whether the window can say either way, which is the one question every
113
+ * figure over a page's words is restricted by.
114
+ *
115
+ * `read` and `skipped` are claims about readers; `unknown` is the absence of
116
+ * one (0282). A passage nothing can be said about is in no mass, out of every
117
+ * list a person acts on, and outside the denominator of every share
118
+ * ([0287](../../decisions/0287-a-share-of-a-pages-words-is-a-share-of-the-words-the-window-can-speak-for-and-spoken-for-is-one-predicate.md)).
119
+ *
120
+ * **Published here rather than spelled where it is asked.** Three modules
121
+ * enumerated the standing by hand and a fourth was about to, and the way that
122
+ * breaks is a sixth `PartStanding`: one spelling has to be revisited and the
123
+ * others go on agreeing with the version of the vocabulary they were written
124
+ * against. Two spellings of a projection that agree today are what the counter
125
+ * keys were before they were published once.
126
+ *
127
+ * **It is not `anchors`.** `change.ts` and `progress.ts` ask the same question
128
+ * of a part under a different name, because what 0221 needs is *can this part
129
+ * anchor a stop* and the answer coincides. A predicate shared because two
130
+ * rules agree is the thing this is fixing.
131
+ */
132
+ export declare const spokenFor: (standing: PartStanding) => boolean;
133
+ /** One line per standing, for a surface putting the reading in front of a person. */
134
+ export declare const describePartStanding: (standing: PartStanding) => string;
135
+ /**
136
+ * Which types declared each role, as a registry answers it.
137
+ *
138
+ * The same shape as `CopyDeclarations` and for the same reason (0122): a
139
+ * registry built by the SDK satisfies it, and so does a two-line double in a
140
+ * test. The inverse — a type's role — is what this module needs and is not what
141
+ * 0114 exposes, because a role is a question asked of the vocabulary rather than
142
+ * of a component. The vocabulary is closed and exported, so the inversion is a
143
+ * walk of `PRIMITIVE_ROLES` rather than a method on the registry.
144
+ */
145
+ export type RoleDeclarations = {
146
+ readonly typesWithRole: (role: PrimitiveRole) => readonly PrimitiveType[];
147
+ };
148
+ /** Everything the join asks of a deployment. A `PrimitiveRegistry` satisfies it. */
149
+ export type PartDeclarations = CopyDeclarations & RoleDeclarations;
150
+ /**
151
+ * One element node of one revision, with whatever the window said about it.
152
+ *
153
+ * In reading order, with the depth and parent an outline carries, because *which
154
+ * parts are read* is a question about a page from the top down: the shape of the
155
+ * answer is where in the page the reading stops, and a set of rows keyed by id
156
+ * cannot show it.
157
+ */
158
+ export type PartReading = {
159
+ readonly nodeId: NodeId;
160
+ readonly type: PrimitiveType;
161
+ /** What part it plays (0114), or `null` where its type declared none. */
162
+ readonly role: PrimitiveRole | null;
163
+ /** 0 at the root. */
164
+ readonly depth: number;
165
+ /** null at the root. */
166
+ readonly parentId: NodeId | null;
167
+ readonly standing: PartStanding;
168
+ /**
169
+ * The counters, or `undefined` where no signal in the window named it.
170
+ *
171
+ * Undefined is not zero and is kept apart from it on purpose. A part with a
172
+ * row of zeroes was reported on; a part with no row was not, and the
173
+ * difference is the whole of how `skipped` is told from a quiet page.
174
+ */
175
+ readonly counters: ReaderTally | undefined;
176
+ /**
177
+ * The words this part says itself: its declared copy props, and the text
178
+ * handed to it directly or through a slot.
179
+ *
180
+ * **Its own, never its subtree's.** Neither a text node nor a slot node is an
181
+ * element, so neither can ever be a part of its own and the words handed into
182
+ * one would otherwise be lost; every other descendant is a part in this same
183
+ * list. So the words of a page are
184
+ * partitioned across its parts exactly once, and a caller may add two rows
185
+ * together without reading a headline twice.
186
+ *
187
+ * `unread` and `unspoken` mean what they mean in the reading they come from
188
+ * (0122): nobody has said whether these props are words, and somebody said
189
+ * these were words and what is in them is not one. The starter library
190
+ * declares `copy` across itself (0223), so `unread` on a page built from it
191
+ * is a deployment's own primitives rather than the framework's silence.
192
+ */
193
+ readonly copy: NodeCopy;
194
+ };
195
+ /**
196
+ * Every part playing one role, added up.
197
+ *
198
+ * **Occurrences only.** `dwellMs`, `activations`, `opens`, `closes` and
199
+ * `completions` are counts of things that happened and they add up across parts.
200
+ * `views`, `reached` and `engaged` count *distinct page views* and are
201
+ * deliberately absent: one reader who read three headings is three in a sum of
202
+ * `reached` and one actual person, which is the distinctness trap 0147 already
203
+ * wrote down one level up. What a role row says about views instead is
204
+ * `standings` — how many of its parts were read, skipped, or cannot be spoken
205
+ * for — which is a count of parts and cannot be mistaken for a count of readers.
206
+ *
207
+ * **`engaged` is absent for a second reason as well.** A press inside a band is
208
+ * one `activations` on the button and one `engaged` on the band, by design
209
+ * (0167). Adding both into one row would count a single reader's single action
210
+ * twice, and the row would look right.
211
+ */
212
+ export type RoleReading = {
213
+ /** `null` is the row for parts whose type declared no role, which is most of a page today. */
214
+ readonly role: PrimitiveRole | null;
215
+ /** Element nodes of this revision playing it. */
216
+ readonly parts: number;
217
+ readonly standings: Readonly<Record<PartStanding, number>>;
218
+ readonly dwellMs: number;
219
+ readonly activations: number;
220
+ readonly opens: number;
221
+ readonly closes: number;
222
+ readonly completions: number;
223
+ };
224
+ export type PageReading = {
225
+ readonly treeId: TreeId;
226
+ readonly revision: number;
227
+ /**
228
+ * The audience whose counters this reading is of, or `null` where nothing
229
+ * said.
230
+ *
231
+ * `null` has two causes and they are a long way apart. A window whose rows
232
+ * never named an audience is one population by construction and is read
233
+ * whole — which is every window written before the column existed (0284) and
234
+ * every one a test builds by hand. A window naming **two**, handed in without a caller saying
235
+ * which was wanted, is two populations and is read as neither: see
236
+ * {@link PageReading.audiences}.
237
+ */
238
+ readonly audienceId: AudienceId | null;
239
+ /**
240
+ * Every audience the window named, whether or not it was the one read.
241
+ *
242
+ * More than one member with {@link PageReading.audienceId} `null` is the
243
+ * refusal: a page served in two forms (0263) has two sets of counters over
244
+ * one tree at one revision, and adding them is one number about two
245
+ * populations, which is the collapse a dimension on the rows exists to
246
+ * prevent (0284). Nothing is read, every part is
247
+ * `unknown`, and the caller is told what it was holding so it can split
248
+ * (`byAudience`) and read twice.
249
+ */
250
+ readonly audiences: readonly AudienceId[];
251
+ /**
252
+ * Counters filed under this tree and revision, in an audience other than the
253
+ * one read, and ignored.
254
+ *
255
+ * Not `foreign`, which is about a page, and not `duplicated`, which is about
256
+ * a row handed in twice. A deployment reading one form's counters out of a
257
+ * window holding both of them is doing the right thing, and this is how much
258
+ * of that window belonged to the other form.
259
+ */
260
+ readonly otherAudience: number;
261
+ /**
262
+ * A floor on the page views the window held, not a count of them.
263
+ *
264
+ * The largest `views` any single part reports. A view that produced no signal
265
+ * about any part is in no row at all, and distinct view counts cannot be added
266
+ * across rows (0147), so the largest row is the most that can be said from
267
+ * counters alone. It is a good floor in practice because a page root is an
268
+ * addressed node and a root is in the viewport of every view that renders.
269
+ *
270
+ * Zero is what makes every standing `unknown`: nothing was measured, so
271
+ * nothing was skipped.
272
+ */
273
+ readonly views: number;
274
+ /** Every element node, in reading order. */
275
+ readonly parts: readonly PartReading[];
276
+ /** Every role in the vocabulary, then the row for parts that declared none. */
277
+ readonly roles: readonly RoleReading[];
278
+ readonly standings: Readonly<Record<PartStanding, number>>;
279
+ /**
280
+ * Counters handed in that are filed under another tree or another revision,
281
+ * and were ignored.
282
+ *
283
+ * Adding two revisions of a node together is the mistake that makes *before
284
+ * versus after a change* unreadable, so this filters rather than trusts its
285
+ * caller — and says how much it dropped, because a caller who passed a whole
286
+ * store's rows and a caller who passed the wrong revision's look identical
287
+ * from the inside.
288
+ */
289
+ readonly foreign: number;
290
+ /**
291
+ * Counters filed under this tree and revision, naming a node this tree does
292
+ * not contain.
293
+ *
294
+ * The alarm for the one failure this join can have that nothing else would
295
+ * catch: a tree and a window that do not belong together. Pass revision 7's
296
+ * counters with revision 6's tree and most parts read `skipped` while the
297
+ * numbers stay plausible. A non-empty list here says the pair is wrong, and
298
+ * names the rows that prove it.
299
+ */
300
+ readonly orphaned: readonly NodeId[];
301
+ /**
302
+ * Nodes handed in more than once, where every row but the first was ignored.
303
+ *
304
+ * A store keeps one row per node per revision per audience (0284) and the
305
+ * audience is picked before this is counted, so this cannot happen from one
306
+ * read — it happens when a caller concatenates two windows instead of letting
307
+ * the store add them. Neither available answer is right: summing is wrong
308
+ * because `views`, `reached` and `engaged` count distinct views and
309
+ * distinctness cannot be added (0147), and overwriting is wrong because the
310
+ * later row is not the truer one. So the first row stands, the rest are
311
+ * dropped, and the fact is reported rather than being a quiet halving of
312
+ * somebody's dwell time.
313
+ */
314
+ readonly duplicated: readonly NodeId[];
315
+ };
316
+ /**
317
+ * Join a window's counters to the tree and registry they were filed against.
318
+ *
319
+ * The tree carries the pair the counters are keyed by, so there is no way to ask
320
+ * this question about a revision without holding the revision — which is the
321
+ * property that makes the answer trustworthy. Rows filed under anything else are
322
+ * dropped and counted.
323
+ *
324
+ * **A reading is of one audience.** A page is one base tree and the deltas an
325
+ * audience earns (0263), so two forms of it are two sets of counters over one
326
+ * tree at one revision, told apart by a column and nothing else (0284). Name
327
+ * the audience and the rest of the window is `otherAudience`; name none and a
328
+ * window holding one audience, or none at all, is read whole. A window holding
329
+ * two with none named is read as neither, because the only other answers are
330
+ * summing two populations and picking one of them by row order.
331
+ */
332
+ export declare const pageReadingOf: (tree: LoomTree, tallies: readonly (ReaderTally & MaybeAudienceScoped)[], declarations: PartDeclarations, audience?: AudienceId) => PageReading;
333
+ /**
334
+ * The words readers actually reached, in reading order.
335
+ *
336
+ * The third question step 6 names, and it is a filter rather than a build: a
337
+ * part's words are its own, so concatenating the read ones double-counts
338
+ * nothing. What it cannot include is a word whose part declared no `copy` —
339
+ * those are in each part's `copy.unread`, named, because a reading that returned
340
+ * them would be guessing and one that dropped them silently would be the failure
341
+ * 0122 exists to prevent.
342
+ */
343
+ export declare const wordsReadIn: (reading: PageReading) => readonly string[];
344
+ //# sourceMappingURL=parts.d.ts.map