@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,182 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ export const ACTION_STANDINGS = everyMemberOf()([
3
+ "acted",
4
+ "untouched",
5
+ "unknown",
6
+ ]);
7
+ export const describeActionStanding = (standing) => {
8
+ switch (standing) {
9
+ case "acted":
10
+ return "readers did something in or to this part";
11
+ case "untouched":
12
+ return "readers reached this part and did nothing in it";
13
+ case "unknown":
14
+ return "nothing in the window can say whether readers acted here";
15
+ }
16
+ };
17
+ const NO_STANDINGS = Object.freeze({
18
+ acted: 0,
19
+ untouched: 0,
20
+ unknown: 0,
21
+ });
22
+ const NO_COUNTS = Object.freeze({
23
+ activations: 0,
24
+ opens: 0,
25
+ closes: 0,
26
+ completions: 0,
27
+ });
28
+ /**
29
+ * Which parts have element parts under them, in one pass over the reading.
30
+ *
31
+ * A part bears children exactly where another part names it as a parent, and
32
+ * every element node of the revision is in the list — so this is a set of
33
+ * parent ids rather than a walk of the tree, and the tree is not read again.
34
+ * Linear rather than a lookup per part: the ledger was quadratic once and a
35
+ * 6,000-node page took 314 ms.
36
+ */
37
+ const parentsIn = (parts) => {
38
+ const parents = new Set();
39
+ for (const part of parts)
40
+ if (part.parentId !== null)
41
+ parents.add(part.parentId);
42
+ return parents;
43
+ };
44
+ /**
45
+ * One part's standing, which is the whole of this module's honesty in nine
46
+ * lines.
47
+ *
48
+ * Ordered so that a claim is only ever reached after everything that would make
49
+ * it unsayable has been ruled out: an absent row first, then an action of any
50
+ * kind, then the structural withholding, then the unanchorable `reached` of 0.
51
+ */
52
+ const standingOf = (counters, uses, bearsParts) => {
53
+ if (counters === undefined)
54
+ return "unknown";
55
+ if (counters.engaged > 0 || uses > 0)
56
+ return "acted";
57
+ if (!bearsParts)
58
+ return "unknown";
59
+ if (counters.reached === 0)
60
+ return "unknown";
61
+ return "untouched";
62
+ };
63
+ const actionOf = (part, parents) => {
64
+ const bearsParts = parents.has(part.nodeId);
65
+ const counts = part.counters === undefined
66
+ ? NO_COUNTS
67
+ : {
68
+ activations: part.counters.activations,
69
+ opens: part.counters.opens,
70
+ closes: part.counters.closes,
71
+ completions: part.counters.completions,
72
+ };
73
+ const uses = counts.activations + counts.opens + counts.closes + counts.completions;
74
+ const reached = part.counters?.reached;
75
+ const within = part.counters?.engaged;
76
+ return {
77
+ nodeId: part.nodeId,
78
+ type: part.type,
79
+ role: part.role,
80
+ depth: part.depth,
81
+ parentId: part.parentId,
82
+ standing: standingOf(part.counters, uses, bearsParts),
83
+ bearsParts,
84
+ reached,
85
+ within,
86
+ share: bearsParts && reached !== undefined && reached > 0 && within !== undefined
87
+ ? within / reached
88
+ : undefined,
89
+ uses,
90
+ counts,
91
+ usesPerReader: uses > 0 && reached !== undefined && reached > 0 ? uses / reached : undefined,
92
+ shutAgain: counts.opens > 0 ? counts.closes / counts.opens : undefined,
93
+ };
94
+ };
95
+ /**
96
+ * Whether a window holds uses and credits them to nobody.
97
+ *
98
+ * A presence test on each side and deliberately not a sum: adding `within`
99
+ * across parts would charge one reader once per level they acted inside
100
+ * (0147, 0167), and a number nobody should add is a number not worth computing.
101
+ *
102
+ * Read off the parts as they came out of the counters, before anything is
103
+ * withheld on account of the answer.
104
+ */
105
+ const unwalkedIn = (parts) => {
106
+ let anyUse = false;
107
+ let anyWithin = false;
108
+ for (const part of parts) {
109
+ if (part.uses > 0)
110
+ anyUse = true;
111
+ if ((part.within ?? 0) > 0)
112
+ anyWithin = true;
113
+ }
114
+ return anyUse && !anyWithin;
115
+ };
116
+ /**
117
+ * One part as a window that credits nobody with being inside anything can
118
+ * honestly report it (0304).
119
+ *
120
+ * Two fields and no others. The share goes because it is `engaged ÷ reached`
121
+ * and `engaged` is the one counter the ancestry walk feeds, so every share in
122
+ * such a window is a nought that is a filing artefact. `untouched` goes because
123
+ * it is read off that same nought — *readers reached this part and did nothing
124
+ * in it* — and becomes `unknown`, which is what the window is.
125
+ *
126
+ * `acted` stays `acted`: a part with uses filed against itself was used, and an
127
+ * occurrence is filed against the part it happened to and needs no ancestry at
128
+ * all. `within` stays as the store holds it, for the reason its own
129
+ * documentation gives.
130
+ */
131
+ const uncredited = (part) => ({
132
+ ...part,
133
+ standing: part.standing === "untouched" ? "unknown" : part.standing,
134
+ share: undefined,
135
+ });
136
+ /**
137
+ * The more ignored of two, which is the ranking rule spelled once.
138
+ *
139
+ * Most readers reached, then the earlier in reading order — and the caller
140
+ * folds in reading order, so `>` rather than `>=` keeps the first of a tie.
141
+ */
142
+ const moreIgnoredOf = (standing, next) => standing === null || (next.reached ?? 0) > (standing.reached ?? 0) ? next : standing;
143
+ /**
144
+ * What readers did on one revision of one page, off the reading of
145
+ * [`parts.ts`](parts.ts) and nothing else.
146
+ *
147
+ * Takes the same `PageReading` every other reading here takes, so a caller that
148
+ * has built one has already paid for the join: no store read, no second walk of
149
+ * the tree, and the counters are the ones already in hand.
150
+ */
151
+ export const pageActionOf = (reading) => {
152
+ const parents = parentsIn(reading.parts);
153
+ const counted = reading.parts.map((part) => actionOf(part, parents));
154
+ const unwalked = unwalkedIn(counted);
155
+ const parts = unwalked ? counted.map(uncredited) : counted;
156
+ const standings = { ...NO_STANDINGS };
157
+ let whole = null;
158
+ let mostIgnored = null;
159
+ let leaves = 0;
160
+ for (const part of parts) {
161
+ standings[part.standing] += 1;
162
+ if (part.depth === 0 && whole === null)
163
+ whole = part;
164
+ if (!part.bearsParts)
165
+ leaves += 1;
166
+ if (part.standing === "untouched" && part !== whole) {
167
+ mostIgnored = moreIgnoredOf(mostIgnored, part);
168
+ }
169
+ }
170
+ return {
171
+ treeId: reading.treeId,
172
+ revision: reading.revision,
173
+ views: reading.views,
174
+ parts,
175
+ standings,
176
+ whole,
177
+ mostIgnored,
178
+ leaves,
179
+ unwalked,
180
+ };
181
+ };
182
+ //# sourceMappingURL=action.js.map
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The fourth contract suite both reader-signal stores are run against, and the
3
+ * one property the three in `src/testing/reader-signal-contract.ts` do not
4
+ * reach: **a whole window, every audience in it, written once**
5
+ * (0316).
6
+ *
7
+ * It is here rather than beside those three because `src/testing/` is another
8
+ * lane's and this is reader-signal work. The finding filed with 0316 asks for
9
+ * it to be moved beside them, which is one import away, and asking is this
10
+ * lane's to do rather than the move.
11
+ *
12
+ * The half that needs two implementations to be worth asserting is not the
13
+ * atomicity — a store in memory cannot fail part-way and has it for nothing,
14
+ * so the rollback is asserted in `postgres.test.ts` against a real database.
15
+ * It is that **two entries naming one audience are added rather than refused**:
16
+ * `ON CONFLICT … DO UPDATE` will not affect one row twice inside one command,
17
+ * so Postgres has to be written to have that and a `Map` has it by
18
+ * construction. A disagreement of exactly that shape is why `counters.ts`
19
+ * exists.
20
+ */
21
+ import type { ReaderTallyStore } from "./tally.js";
22
+ export declare const describeWindowApplyContract: (name: string, make: () => ReaderTallyStore | Promise<ReaderTallyStore>) => void;
23
+ //# sourceMappingURL=applied-window.contract.d.ts.map
@@ -0,0 +1,160 @@
1
+ /**
2
+ * The fourth contract suite both reader-signal stores are run against, and the
3
+ * one property the three in `src/testing/reader-signal-contract.ts` do not
4
+ * reach: **a whole window, every audience in it, written once**
5
+ * (0316).
6
+ *
7
+ * It is here rather than beside those three because `src/testing/` is another
8
+ * lane's and this is reader-signal work. The finding filed with 0316 asks for
9
+ * it to be moved beside them, which is one import away, and asking is this
10
+ * lane's to do rather than the move.
11
+ *
12
+ * The half that needs two implementations to be worth asserting is not the
13
+ * atomicity — a store in memory cannot fail part-way and has it for nothing,
14
+ * so the rollback is asserted in `postgres.test.ts` against a real database.
15
+ * It is that **two entries naming one audience are added rather than refused**:
16
+ * `ON CONFLICT … DO UPDATE` will not affect one row twice inside one command,
17
+ * so Postgres has to be written to have that and a `Map` has it by
18
+ * construction. A disagreement of exactly that shape is why `counters.ts`
19
+ * exists.
20
+ */
21
+ import { describe, expect, it } from "vitest";
22
+ import { DEFAULT_AUDIENCE_ID } from "../audience/audience.js";
23
+ import { nodeId, primitiveType, RIDERS, SKIERS, TREE } from "../testing/reader-signal-contract.js";
24
+ const AT = "2026-10-26T00:00:00.000Z";
25
+ const LATER = "2026-10-26T01:00:00.000Z";
26
+ const unwrap = (result) => {
27
+ if (!result.ok)
28
+ throw new Error(result.error.detail);
29
+ return result.value;
30
+ };
31
+ const tallyOf = (overrides = {}) => ({
32
+ treeId: TREE,
33
+ revision: 1,
34
+ nodeId: nodeId("pricing"),
35
+ type: primitiveType("loom.section"),
36
+ views: 1,
37
+ reached: 1,
38
+ engaged: 0,
39
+ dwellMs: 500,
40
+ activations: 0,
41
+ opens: 0,
42
+ closes: 0,
43
+ completions: 0,
44
+ ...overrides,
45
+ });
46
+ const PAIR = {
47
+ from: { nodeId: nodeId("pricing"), kind: "viewed" },
48
+ to: { nodeId: nodeId("buy"), kind: "activated" },
49
+ };
50
+ const answerOf = (overrides = {}) => ({
51
+ treeId: TREE,
52
+ revision: 1,
53
+ pair: PAIR,
54
+ reached: 2,
55
+ converted: 1,
56
+ ...overrides,
57
+ });
58
+ /** The counters of one audience, read back by the dimension they were filed under. */
59
+ const dwellBy = (rows) => Object.fromEntries(rows.map((row) => [row.audienceId, row.dwellMs]));
60
+ export const describeWindowApplyContract = (name, make) => {
61
+ describe(`${name} — applyWindow contract`, () => {
62
+ it("writes every audience the window held, each against its own row", async () => {
63
+ const store = await make();
64
+ await store.applyWindow([
65
+ { audience: SKIERS, tallies: [tallyOf({ dwellMs: 400 })], funnels: [] },
66
+ { audience: RIDERS, tallies: [tallyOf({ dwellMs: 600 })], funnels: [] },
67
+ ], AT);
68
+ const rows = unwrap(await store.tallies());
69
+ expect(rows).toHaveLength(2);
70
+ expect(dwellBy(rows)).toEqual({ [SKIERS]: 400, [RIDERS]: 600 });
71
+ });
72
+ /**
73
+ * Additive across windows, like `apply` is: what one run writes is *what
74
+ * this window added*, never *what is true so far*.
75
+ */
76
+ it("adds a second window to the first rather than replacing it", async () => {
77
+ const store = await make();
78
+ await store.applyWindow([{ audience: SKIERS, tallies: [tallyOf({ views: 2 })], funnels: [] }], AT);
79
+ await store.applyWindow([{ audience: SKIERS, tallies: [tallyOf({ views: 5 })], funnels: [] }], LATER);
80
+ expect(unwrap(await store.tallies())[0]).toMatchObject({ views: 7, updatedAt: LATER });
81
+ });
82
+ /**
83
+ * The one a caller can produce and neither store may refuse. A window
84
+ * folded per audience cannot hand over two entries for one audience, but
85
+ * the interface is public and the two implementations must not differ about
86
+ * what happens when something does.
87
+ */
88
+ it("adds two entries naming one audience rather than refusing the write", async () => {
89
+ const store = await make();
90
+ const applied = await store.applyWindow([
91
+ { audience: SKIERS, tallies: [tallyOf({ dwellMs: 300, views: 1 })], funnels: [] },
92
+ { audience: SKIERS, tallies: [tallyOf({ dwellMs: 200, views: 2 })], funnels: [] },
93
+ ], AT);
94
+ expect(applied.ok).toBe(true);
95
+ const rows = unwrap(await store.tallies());
96
+ expect(rows).toHaveLength(1);
97
+ expect(rows[0]).toMatchObject({ dwellMs: 500, views: 3 });
98
+ });
99
+ it("writes the funnels and the appearances of each audience too", async () => {
100
+ const store = await make();
101
+ await store.applyWindow([
102
+ {
103
+ audience: SKIERS,
104
+ tallies: [],
105
+ funnels: [answerOf({ reached: 4, converted: 1 })],
106
+ appearances: [{ treeId: TREE, revision: 1, views: 4 }],
107
+ },
108
+ {
109
+ audience: RIDERS,
110
+ tallies: [],
111
+ funnels: [answerOf({ reached: 9, converted: 3 })],
112
+ appearances: [{ treeId: TREE, revision: 1, views: 9 }],
113
+ },
114
+ ], AT);
115
+ const funnels = unwrap(await store.funnels());
116
+ const views = unwrap(await store.pageViews());
117
+ expect(Object.fromEntries(funnels.map((row) => [row.audienceId, row.reached]))).toEqual({
118
+ [SKIERS]: 4,
119
+ [RIDERS]: 9,
120
+ });
121
+ expect(Object.fromEntries(views.map((row) => [row.audienceId, row.appearances]))).toEqual({
122
+ [SKIERS]: 4,
123
+ [RIDERS]: 9,
124
+ });
125
+ });
126
+ /** Omitted is `aud_everyone`, on the same terms as `apply`'s third argument. */
127
+ it("files an entry that names no audience under the default one", async () => {
128
+ const store = await make();
129
+ await store.applyWindow([{ tallies: [tallyOf()], funnels: [] }], AT);
130
+ expect(unwrap(await store.tallies())[0]).toMatchObject({ audienceId: DEFAULT_AUDIENCE_ID });
131
+ });
132
+ it("takes an empty window, and a window of empty entries, without writing anything", async () => {
133
+ const store = await make();
134
+ expect(unwrap(await store.applyWindow([], AT))).toBeUndefined();
135
+ expect(unwrap(await store.applyWindow([{ audience: SKIERS, tallies: [], funnels: [] }], AT))).toBeUndefined();
136
+ expect(unwrap(await store.tallies())).toEqual([]);
137
+ expect(unwrap(await store.pageViews())).toEqual([]);
138
+ });
139
+ /**
140
+ * `apply` is this method over a single entry, and both stores implement it
141
+ * as exactly that — so the assertion is that the two routes are the same
142
+ * write rather than two spellings of one.
143
+ */
144
+ it("writes through `apply` what one entry through `applyWindow` writes", async () => {
145
+ const [viaApply, viaWindow] = [await make(), await make()];
146
+ const counters = {
147
+ tallies: [tallyOf({ dwellMs: 700, engaged: 1 })],
148
+ funnels: [answerOf()],
149
+ appearances: [{ treeId: TREE, revision: 1, views: 3 }],
150
+ };
151
+ const audience = SKIERS;
152
+ await viaApply.apply(counters, AT, audience);
153
+ await viaWindow.applyWindow([{ audience, ...counters }], AT);
154
+ expect(unwrap(await viaApply.tallies())).toEqual(unwrap(await viaWindow.tallies()));
155
+ expect(unwrap(await viaApply.funnels())).toEqual(unwrap(await viaWindow.funnels()));
156
+ expect(unwrap(await viaApply.pageViews())).toEqual(unwrap(await viaWindow.pageViews()));
157
+ });
158
+ });
159
+ };
160
+ //# sourceMappingURL=applied-window.contract.js.map
@@ -0,0 +1,210 @@
1
+ import type { CollectionHealth } from "./health.js";
2
+ /**
3
+ * Whether nothing is arriving because nothing is posting, or because this
4
+ * deployment's door is turning it away.
5
+ *
6
+ * Every reading in this subsystem is a reading of rows that arrived. A part
7
+ * that nobody reached, a window with no page views, a funnel nobody entered, a
8
+ * census of the reasons a reading went dark — all of them are computed from
9
+ * counters, and a counter that was never written looks exactly like a counter
10
+ * that was written with a nought. So the most ordinary failure a new
11
+ * deployment has — a snippet posting from an origin its project does not name
12
+ * — makes **forty-odd readings and nine comparisons all say the same wrong
13
+ * thing**: *nobody read this page.*
14
+ *
15
+ * The evidence that it is wrong has existed since
16
+ * [0311](../../decisions/0311-a-refusal-whose-key-was-right-is-counted-against-its-project-and-one-without-one-is-not.md):
17
+ * the door counts what it refused, per reason, with the newest one's origin
18
+ * beside it. **Nothing joined the two.** A person could read a refusal count
19
+ * in one box on a screen and a page of nought-view pages in another and draw
20
+ * the conclusion themselves; no reading drew it, so no verdict, no fault and no
21
+ * sentence anywhere in this subsystem could.
22
+ *
23
+ * ## Why it is not a collection fault
24
+ *
25
+ * {@link collectionHealthOf} publishes seven faults and every one of them is
26
+ * **about one revision of one page**, because every one is derived from that
27
+ * revision's own rows. A refusal names no page: a delivery turned away for
28
+ * naming the wrong site was turned away before anything read which tree it was
29
+ * about, and reading the body to find out would spend the deployment's database
30
+ * on exactly the sender the gate exists to stop (0311). So this is deployment-
31
+ * wide by construction, which is a different subject (0240) and therefore a
32
+ * reading beside health rather than an eighth member of a closed set inside it.
33
+ *
34
+ * ## The reasons stay the deployment's
35
+ *
36
+ * Why a host turned a sender away is the host's business — which is why the
37
+ * counter is the deployment's table and not the runtime's — so this reading is
38
+ * generic in the reason and never names one. A host hands in its own closed
39
+ * set and gets it back on {@link ArrivalStanding.newest}, where its own
40
+ * sentence and its own remedy can be chosen from it. The framework's part is
41
+ * the join and the standing, both of which hold whatever the reasons are.
42
+ *
43
+ * Pure, linear in the tallies handed in, and reaches no store, clock or DOM.
44
+ */
45
+ /**
46
+ * One reason a door turned deliveries away, as a deployment's own counter holds
47
+ * it.
48
+ *
49
+ * Structural rather than imported, for the reason above: the three members this
50
+ * deployment happens to count are not the framework's to know. `TReason` is
51
+ * whatever a host's closed set is, and it travels through to `newest` so that
52
+ * the one place a reason is acted on is the host's own switch over its own set.
53
+ */
54
+ export type TurnedAwayTally<TReason extends string = string> = {
55
+ readonly reason: TReason;
56
+ /** Deliveries turned away for this reason, cumulative since the counter existed. */
57
+ readonly refused: number;
58
+ /** When the newest of them was turned away, in epoch milliseconds. */
59
+ readonly lastAt: number;
60
+ /**
61
+ * The site the newest of them came from, as an origin, or `null` where it
62
+ * named none.
63
+ *
64
+ * Carried because for the commonest reason it is the whole remedy: *from
65
+ * `https://loomjs.org`* beside a project that names `www.loomjs.org` needs no
66
+ * other explanation.
67
+ */
68
+ readonly lastOrigin: string | null;
69
+ };
70
+ /** The newest delivery this door turned away, which is the one an operator acts on. */
71
+ export type NewestTurnedAway<TReason extends string = string> = {
72
+ readonly reason: TReason;
73
+ readonly origin: string | null;
74
+ /** When it was turned away, in epoch milliseconds, as the counter holds it. */
75
+ readonly atMs: number;
76
+ /**
77
+ * How long before the instant handed in it was turned away, or `null` where
78
+ * no instant was.
79
+ *
80
+ * The one number that tells a live fault from a fixed one: a cumulative
81
+ * counter cannot say whether its own figure is current, and a deployment that
82
+ * was misconfigured a month ago and fixed it still holds every refusal it
83
+ * ever counted. Negative where the counter is ahead of the instant, by the
84
+ * same subtraction rather than by a special case (0274).
85
+ */
86
+ readonly sinceMs: number | null;
87
+ };
88
+ /** Whether anything is arriving at this deployment, and why not. */
89
+ export type ArrivalStandingName =
90
+ /**
91
+ * Nothing offered a count of what the door turned away, so the question
92
+ * cannot be answered either way.
93
+ *
94
+ * The refusal rather than the gap, and it wins over every other state for the
95
+ * reason an absent region store is not an empty map (0240): a window with
96
+ * nothing in it and no refusal counter beside it is *two* states, and calling
97
+ * it `silent` would publish the more comforting one. A deployment that keeps
98
+ * no such counter — or whose store was not reachable on this read — gets the
99
+ * figures it does have and no verdict.
100
+ */
101
+ "unasked"
102
+ /**
103
+ * Nothing has been collected and nothing has been turned away.
104
+ *
105
+ * No page is posting to this deployment at all: the snippet is absent, or the
106
+ * broadcaster was never called, or the signals never left the browser. The
107
+ * strongest of the quiet answers, because the door is the one place a
108
+ * delivery cannot arrive without being seen, and it saw none.
109
+ */
110
+ | "silent"
111
+ /**
112
+ * Nothing has been collected and deliveries have been turned away.
113
+ *
114
+ * **The state this reading exists for.** A page is posting and this door is
115
+ * refusing it, and every other reading in the subsystem is reporting that
116
+ * nobody read anything. It is the one standing here that no amount of age on
117
+ * the counter can weaken: whenever those refusals happened, nothing has ever
118
+ * been collected, so there is no window in which this deployment was working.
119
+ */
120
+ | "turned-away"
121
+ /** Something has been collected and nothing has been turned away. */
122
+ | "collecting"
123
+ /**
124
+ * Something has been collected and deliveries have been turned away.
125
+ *
126
+ * Both are true and neither is the whole picture: a second sender with a
127
+ * stale key, one page of several carrying the wrong snippet, or a
128
+ * misconfiguration since fixed. `newest.sinceMs` is what tells those apart
129
+ * and this standing deliberately does not try to.
130
+ */
131
+ | "mixed";
132
+ /** The closed set, in the order a surface reads them: the refusal, then the two quiet states, then the two live ones. */
133
+ export declare const ARRIVAL_STANDINGS: readonly ArrivalStandingName[];
134
+ /** What is arriving at a deployment, what is being turned away, and what that means together. */
135
+ export type ArrivalStanding<TReason extends string = string> = {
136
+ readonly standing: ArrivalStandingName;
137
+ /**
138
+ * Revisions anything at all was collected about, which is **not** a count of
139
+ * readers.
140
+ *
141
+ * A revision stands here if the window held one counter, one funnel answer,
142
+ * one door row or one region bucket for it, so a deployment whose senders
143
+ * never mark an opening still reads as collecting — which it is. Reading this
144
+ * off `arrivals` instead would call that deployment `turned-away` and send an
145
+ * operator after a gate that is letting everything through.
146
+ */
147
+ readonly collected: number;
148
+ /**
149
+ * Page views counted at the door across every revision read, added.
150
+ *
151
+ * The headcount behind `collected`, carried through unchanged. Nought with a
152
+ * positive `collected` is an ordinary state and its own fault already
153
+ * (`door-unscaled`), not a sign that nothing arrived.
154
+ */
155
+ readonly arrivals: number;
156
+ /**
157
+ * Deliveries turned away, added across the reasons, or `null` where nothing
158
+ * offered a count.
159
+ *
160
+ * The two kinds of nothing kept apart (0240): `null` is *nobody counted*, and
161
+ * `0` is *the counter was read and holds none*.
162
+ */
163
+ readonly refused: number | null;
164
+ /** The newest delivery turned away, or `null` where none was. */
165
+ readonly newest: NewestTurnedAway<TReason> | null;
166
+ /**
167
+ * Tallies beyond the first for one reason, dropped.
168
+ *
169
+ * A store keys its rows by the reason, so this is nought from every store in
170
+ * this repository. It is counted because the one lie a sum can be told is a
171
+ * row handed in twice, and a count that has been added cannot be unadded
172
+ * (0158) — a caller that concatenated two reads would otherwise publish twice
173
+ * the refusals with nothing saying so.
174
+ */
175
+ readonly duplicated: number;
176
+ };
177
+ /**
178
+ * Read a window's health and a door's refusals together, into the one question
179
+ * neither can answer alone.
180
+ *
181
+ * The health is taken as the `Pick` a reading of the window already produced
182
+ * rather than as two loose numbers, so what is judged here is what that reading
183
+ * published, by construction rather than by a reviewer — the shape
184
+ * {@link retentionPromiseOf} takes the retention in (0321). The two fields are
185
+ * the two it needs and the two a caller could most plausibly get wrong by hand:
186
+ * a view floor is not an arrival count (0212), and a count of readers is not a
187
+ * count of pages.
188
+ *
189
+ * **A delivery was turned away if any reason reports a positive count**, which
190
+ * is the one rule the standing turns on, and it is the same rule `newest` is
191
+ * found by — so a standing that names a refusal always carries the refusal it
192
+ * named.
193
+ *
194
+ * **The instant is optional and nothing here reads a clock.** A caller that
195
+ * states one gets `sinceMs` and can tell a live fault from a fixed one; a
196
+ * caller that does not gets every other figure and no age, which is the shape a
197
+ * collection schedule already takes (0274). A reading that read the wall clock
198
+ * would answer differently on two calls over one set of rows.
199
+ */
200
+ export declare const arrivalStandingOf: <TReason extends string>(health: Pick<CollectionHealth, "pages" | "arrivals">, turnedAway: readonly TurnedAwayTally<TReason>[] | undefined, at?: number) => ArrivalStanding<TReason>;
201
+ /**
202
+ * One line for the operator setting a deployment up, because they are the only
203
+ * person who can close the gap.
204
+ *
205
+ * It names the reason as the deployment spelled it and never translates one: a
206
+ * host's own set is the host's to put a sentence and a remedy to, and a
207
+ * framework that worded them would be wording a vocabulary it does not define.
208
+ */
209
+ export declare const describeArrivalStanding: (standing: ArrivalStanding) => string;
210
+ //# sourceMappingURL=arriving.d.ts.map