@jam-overture/loom 0.2.0 → 0.3.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 (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,295 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { readingKeyOf } from "./audiences.js";
3
+ import { spoilsTheConversion, spoilsTheLoss, } from "./health.js";
4
+ export const AGENDA_WORK = everyMemberOf()([
5
+ "page",
6
+ "collection",
7
+ "both",
8
+ "none",
9
+ ]);
10
+ /** One line per member, for a surface saying what a row is asking for. */
11
+ export const describeAgendaWork = (work) => {
12
+ switch (work) {
13
+ case "page":
14
+ return "rewrite the page: its readers stop reading or stop answering, and the figure can be trusted";
15
+ case "collection":
16
+ return "repair the measurement: what this page reports cannot be acted on";
17
+ case "both":
18
+ return "rewrite the page, and repair a fault that does not reach the figure it was ranked by";
19
+ case "none":
20
+ return "nothing any of the three readings asks for";
21
+ }
22
+ };
23
+ export const AGENDA_SUBJECTS = everyMemberOf()([
24
+ "pages",
25
+ "intake",
26
+ "silence",
27
+ "unverified",
28
+ ]);
29
+ /** One line per member, for a surface saying what a fix-list is about. */
30
+ export const describeAgendaSubject = (subject) => {
31
+ switch (subject) {
32
+ case "pages":
33
+ return "these are this deployment's pages, and the rows below can be acted on";
34
+ case "intake":
35
+ return "nothing has been collected and deliveries are being turned away: repair the intake";
36
+ case "silence":
37
+ return "nothing has been collected and nothing has been turned away: no page is posting";
38
+ case "unverified":
39
+ return "nothing has been collected, and nothing says whether anything was turned away";
40
+ }
41
+ };
42
+ const EMPTY_WORK = Object.freeze(Object.fromEntries(AGENDA_WORK.map((work) => [work, 0])));
43
+ /** Tree id, then newest revision first, then form — the order both readings publish. */
44
+ const byPage = (one, other) => one.treeId.localeCompare(other.treeId) ||
45
+ other.revision - one.revision ||
46
+ (one.audienceId ?? "").localeCompare(other.audienceId ?? "");
47
+ /**
48
+ * Rows filed under `readingKeyOf`, with the first appearance of a key kept.
49
+ *
50
+ * The first and not the last for the reason the counter fold keeps the standing
51
+ * row: a caller's two reads of one page are the same page, and which of the two
52
+ * copies is answered must not depend on the order they were concatenated in.
53
+ */
54
+ const byKey = (rows) => {
55
+ const first = new Map();
56
+ let duplicated = 0;
57
+ for (const row of rows) {
58
+ const key = readingKeyOf(row);
59
+ if (first.has(key))
60
+ duplicated += 1;
61
+ else
62
+ first.set(key, row);
63
+ }
64
+ return { first, duplicated };
65
+ };
66
+ /**
67
+ * What one row asks for, out of what each order ranked and what a fault reaches.
68
+ *
69
+ * `evidence` is *at least one rank this deployment may act on* — a fall no fault
70
+ * reaches, or a leak no fault reaches. The two are asked separately because the
71
+ * two answers differ (0336), and `ranked` is *either order put the page in it*,
72
+ * because a page with a rank nobody may act on is collection work whichever
73
+ * order gave it.
74
+ */
75
+ const workOf = (ranked, faulted, evidence) => {
76
+ if (!faulted)
77
+ return ranked ? "page" : "none";
78
+ return evidence ? "both" : "collection";
79
+ };
80
+ /**
81
+ * Whether this row belongs in a page order, asked **per order** rather than off
82
+ * {@link AgendaRow.work}.
83
+ *
84
+ * `work` is `page` or `both` wherever *some* rank is evidence, so reading it to
85
+ * fill both lists would put a page whose fall a fault manufactured into the
86
+ * order of falls on the strength of its sound leak, and the other way round.
87
+ * That is the 0330 defect reintroduced by a shortcut, and it is the one thing a
88
+ * reader of this file should not simplify back (0336).
89
+ */
90
+ const asksToRewriteTheFall = (row) => row.order.standing === "ranked" && !row.spoiled;
91
+ const asksToRewriteTheLeak = (row) => row.conversion.standing === "ranked" && !row.spoiledConversion;
92
+ const asksForCollection = (row) => row.work === "collection" || row.work === "both";
93
+ /**
94
+ * Whether a door turned anything away, as an arrival standing says it, or
95
+ * `null` where nothing can say.
96
+ *
97
+ * Exhaustive over the standing rather than a test for one member, so that a
98
+ * sixth arrival standing cannot be added without this file being asked what it
99
+ * means here. Two of the five are the same answer for opposite reasons — a
100
+ * deployment that collected nothing and one that collected everything both
101
+ * turned nothing away — and collapsing them is correct, because the other half
102
+ * of the subject is taken from the rows.
103
+ */
104
+ const turnedAnythingAway = (standing) => {
105
+ switch (standing) {
106
+ case "unasked":
107
+ return null;
108
+ case "silent":
109
+ case "collecting":
110
+ return false;
111
+ case "turned-away":
112
+ case "mixed":
113
+ return true;
114
+ }
115
+ };
116
+ /**
117
+ * What a fix-list is about, out of whether it has pages and whether a door
118
+ * refused anything.
119
+ *
120
+ * `collected` is the health reading's own pages, counted once — the rows are
121
+ * joined from them, so this is a claim about the rows rather than about a
122
+ * number carried in from somewhere else.
123
+ */
124
+ const subjectOf = (collected, arrival) => {
125
+ if (collected)
126
+ return "pages";
127
+ const refused = arrival === null ? null : turnedAnythingAway(arrival.standing);
128
+ if (refused === null)
129
+ return "unverified";
130
+ return refused ? "intake" : "silence";
131
+ };
132
+ /**
133
+ * Join an order of a deployment's pages to the health of its collection, and
134
+ * publish the two orders that come out.
135
+ *
136
+ * ```ts
137
+ * const assembly = windowAssemblyOf(window, context)
138
+ * const progress = assembly.readings.pages.map(readingProgressOf)
139
+ * const health = collectionHealthOf(assembly.readings.pages, window.pageViews, schedule)
140
+ * const agenda = deploymentAgendaOf(
141
+ * deploymentReadingOf(progress, window.pageViews),
142
+ * deploymentConversionOf(windowFunnelsOf(window, assembly).pages),
143
+ * health,
144
+ * arrivalStandingOf(health, turnedAway, at),
145
+ * deploymentUnreadOf(assembly.readings.pages.map(pageFrontierOf))
146
+ * )
147
+ * ```
148
+ *
149
+ * The three readings are handed in rather than derived from a window here, for
150
+ * the reason every derived reading in this subsystem takes readings: each is
151
+ * separately useful and separately drawn, and deriving any of them a second time
152
+ * is how two screens come to disagree about one deployment.
153
+ *
154
+ * @param arrival Whether anything is arriving at this deployment, as
155
+ * `arrivalStandingOf` answered it, or `null` where the caller read no refusal
156
+ * counter and has no answer to hand in. **Required rather than optional**, on
157
+ * the terms the schedule above it is required
158
+ * ([0322](../../decisions/0322-a-window-is-read-off-one-deployment-context-and-the-region-floor-is-not-optional.md),
159
+ * [0343](../../decisions/0343-a-deployments-fix-list-is-read-off-one-window-and-states-its-collection-schedule-or-says-it-has-none.md)):
160
+ * an argument a caller may omit is a fix-list that type-checks, runs, and
161
+ * cannot tell *nothing to fix* from *nothing to fix it with*, which is the
162
+ * state this subsystem's commonest setup failure puts a deployment in.
163
+ *
164
+ * `null` and a standing of `unasked` are **one answer** and both read
165
+ * `unverified`: a caller with no counter to read and a deployment with no
166
+ * counter to offer are the same absence, and inventing a second word for it
167
+ * would be a sixth member of a closed set of five, said twice.
168
+ *
169
+ * Only {@link ArrivalStanding.standing} is taken. Nothing else on it is needed
170
+ * and a copy of its collected count would be a second answer to a question the
171
+ * rows already answer.
172
+ *
173
+ * @param unread The deployment's pages as the order of **places** has them, as
174
+ * `deploymentUnreadOf` answered it. **Required rather than optional**, on the
175
+ * terms the three readings above it are (0322, 0343): a fix-list that says
176
+ * *rewrite this page* and cannot say where on it is the state this lane filed
177
+ * on 9 November, and an argument a caller may omit is that fix-list
178
+ * type-checking.
179
+ *
180
+ * **It cannot change a row, a list, a count of work or `first`** — it is read
181
+ * onto rows the three readings above made, and a page it does not name keeps
182
+ * its row with `null` on it. A deployment that asks nothing to be rewritten and
183
+ * has a band nobody reads still reads `none` work, because the key here is
184
+ * parts of a page and the three orders are readers, and there is nothing to
185
+ * compare (0327, 0377, 0378).
186
+ */
187
+ export const deploymentAgendaOf = (order, conversion, health, arrival, unread) => {
188
+ const ranked = byKey([...order.ranked, ...order.unranked]);
189
+ const leaks = byKey([...conversion.ranked, ...conversion.unranked]);
190
+ const states = byKey(health.pages);
191
+ /**
192
+ * The places reading filed the same way as the three above it, and keyed by
193
+ * the same rule — so two forms of one page take their own places, which are
194
+ * not each other's (0300), and a hand-built reading holding one page twice is
195
+ * counted rather than silently preferred.
196
+ *
197
+ * `deploymentUnreadOf` deduplicates its own input, so `duplicated` is nought
198
+ * from every published route. It is added in anyway, on the rule the other
199
+ * three are here under: a count that has been doubled cannot be undoubled
200
+ * (0158), and this is the one place that would see it.
201
+ */
202
+ const places = byKey([...unread.ranked, ...unread.unranked]);
203
+ let placed = 0;
204
+ const rowOf = (page) => {
205
+ const key = readingKeyOf(page);
206
+ const state = states.first.get(key);
207
+ const leak = leaks.first.get(key);
208
+ if (state === undefined || leak === undefined)
209
+ return null;
210
+ /**
211
+ * Read onto the row and never required for it. The three readings above
212
+ * decide whether there is a row; this decides whether that row knows where
213
+ * on the page to go, and a short fourth reading must not be able to shrink
214
+ * a fix-list (0378).
215
+ */
216
+ const place = places.first.get(key) ?? null;
217
+ if (place !== null)
218
+ placed += 1;
219
+ const faulted = state.standing === "faulted";
220
+ const fell = page.standing === "ranked";
221
+ const leaked = leak.standing === "ranked";
222
+ const spoiled = fell && state.faults.some(spoilsTheLoss);
223
+ const spoiledConversion = leaked && state.faults.some(spoilsTheConversion);
224
+ return {
225
+ treeId: page.treeId,
226
+ revision: page.revision,
227
+ audienceId: page.audienceId,
228
+ work: workOf(fell || leaked, faulted, (fell && !spoiled) || (leaked && !spoiledConversion)),
229
+ spoiled,
230
+ spoiledConversion,
231
+ order: page,
232
+ conversion: leak,
233
+ health: state,
234
+ unread: place,
235
+ };
236
+ };
237
+ /**
238
+ * One row per key, built once and looked up by every order below — so the two
239
+ * orders and the slice are three views of one set of rows rather than three
240
+ * constructions of it, and `work` cannot differ between them.
241
+ */
242
+ const joined = new Map();
243
+ for (const page of ranked.first.values()) {
244
+ const row = rowOf(page);
245
+ if (row !== null)
246
+ joined.set(readingKeyOf(page), row);
247
+ }
248
+ const rows = [...joined.values()].sort(byPage);
249
+ /**
250
+ * The rows of one source list, in that list's own order, each at most once.
251
+ *
252
+ * **The dedup is here as well as on the join**, which is the one thing a
253
+ * reader of this file should not simplify away: the published orders walk the
254
+ * caller's lists rather than the joined map, so a caller's two reads of one
255
+ * page put the page in an order twice while the counts above it stay right —
256
+ * and a page twice in an order is exactly how an order lies about how much
257
+ * there is to fix (0250, 0158).
258
+ */
259
+ const taken = (pages, wanted, already) => pages.flatMap((page) => {
260
+ const key = readingKeyOf(page);
261
+ const row = joined.get(key);
262
+ if (row === undefined || already.has(key) || !wanted(row))
263
+ return [];
264
+ already.add(key);
265
+ return [row];
266
+ });
267
+ const inCollection = new Set();
268
+ const page = taken(order.ranked, asksToRewriteTheFall, new Set());
269
+ const converting = taken(conversion.ranked, asksToRewriteTheLeak, new Set());
270
+ const collection = [
271
+ ...taken(health.faulted, asksForCollection, inCollection),
272
+ ...taken(health.unpriced, asksForCollection, inCollection),
273
+ ];
274
+ const contested = collection.filter((row) => row.spoiled || row.spoiledConversion);
275
+ const work = rows.reduce((counted, row) => ({ ...counted, [row.work]: counted[row.work] + 1 }), { ...EMPTY_WORK });
276
+ return {
277
+ subject: subjectOf(states.first.size > 0, arrival),
278
+ rows,
279
+ page,
280
+ converting,
281
+ collection,
282
+ contested,
283
+ first: contested[0] ?? page[0] ?? converting[0] ?? collection[0] ?? null,
284
+ work,
285
+ trees: new Set(rows.map((row) => row.treeId)).size,
286
+ unpaired: {
287
+ order: ranked.first.size - joined.size,
288
+ health: states.first.size - joined.size,
289
+ conversion: leaks.first.size - joined.size,
290
+ unread: places.first.size - placed,
291
+ },
292
+ duplicated: ranked.duplicated + leaks.duplicated + states.duplicated + places.duplicated,
293
+ };
294
+ };
295
+ //# sourceMappingURL=agenda.js.map
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The sixth contract suite both reader-signal tally stores are run against:
3
+ * **page views are counted under the hour they began in, and the hours of a
4
+ * revision sum to its total** (`arrivals.ts`).
5
+ *
6
+ * It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
7
+ * for the reason `applied-window.contract.ts` and `kept.contract.ts` are: that
8
+ * directory is another lane's and this is reader-signal work. The finding filed
9
+ * with 0316 asks for the set to be moved together, which is one import away.
10
+ *
11
+ * **Every property here needs two implementations to be worth asserting.** The
12
+ * hour is a `timestamptz` in one store and a number in the other, so a bucket
13
+ * is a `Date` that has to come back as the instant it went in as; the pair of
14
+ * writes is a transaction in one and two map writes in the other; and two
15
+ * counts of one hour in a single call are an `ON CONFLICT` Postgres **raises**
16
+ * on and a `Map` silently overwrites. Each of those is a way for a chart to
17
+ * stop summing to the counter it is drawn beside, which is permanent (0158).
18
+ */
19
+ import type { ReaderTallyStore } from "./tally.js";
20
+ export declare const describeArrivalHourContract: (name: string, make: () => Promise<ReaderTallyStore> | ReaderTallyStore) => void;
21
+ //# sourceMappingURL=arrivals.contract.d.ts.map
@@ -0,0 +1,180 @@
1
+ /**
2
+ * The sixth contract suite both reader-signal tally stores are run against:
3
+ * **page views are counted under the hour they began in, and the hours of a
4
+ * revision sum to its total** (`arrivals.ts`).
5
+ *
6
+ * It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
7
+ * for the reason `applied-window.contract.ts` and `kept.contract.ts` are: that
8
+ * directory is another lane's and this is reader-signal work. The finding filed
9
+ * with 0316 asks for the set to be moved together, which is one import away.
10
+ *
11
+ * **Every property here needs two implementations to be worth asserting.** The
12
+ * hour is a `timestamptz` in one store and a number in the other, so a bucket
13
+ * is a `Date` that has to come back as the instant it went in as; the pair of
14
+ * writes is a transaction in one and two map writes in the other; and two
15
+ * counts of one hour in a single call are an `ON CONFLICT` Postgres **raises**
16
+ * on and a `Map` silently overwrites. Each of those is a way for a chart to
17
+ * stop summing to the counter it is drawn beside, which is permanent (0158).
18
+ */
19
+ import { describe, expect, it } from "vitest";
20
+ import { OTHER_TREE, RIDERS, SKIERS, TREE } from "../testing/reader-signal-contract.js";
21
+ import { ARRIVAL_HOUR_MS } from "./arrivals.js";
22
+ const HOUR = ARRIVAL_HOUR_MS;
23
+ const MIDNIGHT = Date.parse("2026-11-06T00:00:00.000Z");
24
+ const at = (hour, minutes = 0) => new Date(MIDNIGHT + hour * HOUR + minutes * 60_000).toISOString();
25
+ const opening = (views, overrides = {}) => ({
26
+ treeId: TREE,
27
+ revision: 1,
28
+ views,
29
+ ...overrides,
30
+ });
31
+ const unwrap = (result) => {
32
+ if (!result.ok)
33
+ throw new Error(result.error.detail);
34
+ return result.value;
35
+ };
36
+ export const describeArrivalHourContract = (name, make) => {
37
+ describe(`${name} — page views by the hour they began in`, () => {
38
+ const counted = async () => {
39
+ const store = await make();
40
+ unwrap(await store.opened([opening(2)], at(9, 15), SKIERS));
41
+ return store;
42
+ };
43
+ it("files an arrival under the hour of the instant it was counted at", async () => {
44
+ const store = await counted();
45
+ const { hours } = unwrap(await store.arrivals());
46
+ expect(hours).toEqual([
47
+ {
48
+ audienceId: SKIERS,
49
+ treeId: TREE,
50
+ revision: 1,
51
+ hour: MIDNIGHT + 9 * HOUR,
52
+ views: 2,
53
+ updatedAt: at(9, 15),
54
+ },
55
+ ]);
56
+ });
57
+ it("adds a second delivery in the same hour to the same row", async () => {
58
+ const store = await counted();
59
+ unwrap(await store.opened([opening(3)], at(9, 59), SKIERS));
60
+ const { hours } = unwrap(await store.arrivals());
61
+ expect(hours).toHaveLength(1);
62
+ expect(hours[0]?.views).toBe(5);
63
+ });
64
+ it("puts a delivery one minute later in the next hour", async () => {
65
+ const store = await counted();
66
+ unwrap(await store.opened([opening(3)], at(10, 0), SKIERS));
67
+ const { hours } = unwrap(await store.arrivals());
68
+ expect(hours.map((row) => [row.hour, row.views])).toEqual(expect.arrayContaining([
69
+ [MIDNIGHT + 9 * HOUR, 2],
70
+ [MIDNIGHT + 10 * HOUR, 3],
71
+ ]));
72
+ });
73
+ /**
74
+ * Two entries naming one hour inside a single call are added, which is the
75
+ * guarantee `counters.ts` gives in front of the driver: Postgres refuses to
76
+ * affect one row twice in one command and a `Map` would keep the last.
77
+ */
78
+ it("adds two openings of one revision handed over together", async () => {
79
+ const store = await make();
80
+ unwrap(await store.opened([opening(2), opening(3)], at(9), SKIERS));
81
+ const { hours } = unwrap(await store.arrivals());
82
+ expect(hours).toHaveLength(1);
83
+ expect(hours[0]?.views).toBe(5);
84
+ });
85
+ it("keeps an hour of two audiences apart (0284)", async () => {
86
+ const store = await counted();
87
+ unwrap(await store.opened([opening(4)], at(9, 30), RIDERS));
88
+ const { hours } = unwrap(await store.arrivals());
89
+ expect(hours).toHaveLength(2);
90
+ expect(unwrap(await store.arrivals({ audience: RIDERS })).hours[0]?.views).toBe(4);
91
+ });
92
+ it("keeps an hour of two trees apart", async () => {
93
+ const store = await counted();
94
+ unwrap(await store.opened([opening(4, { treeId: OTHER_TREE })], at(9, 30), SKIERS));
95
+ expect(unwrap(await store.arrivals()).hours).toHaveLength(2);
96
+ expect(unwrap(await store.arrivals({ treeId: TREE })).hours).toHaveLength(1);
97
+ });
98
+ it("keeps an hour of two revisions apart", async () => {
99
+ const store = await counted();
100
+ unwrap(await store.opened([opening(4, { revision: 2 })], at(9, 30), SKIERS));
101
+ expect(unwrap(await store.arrivals()).hours).toHaveLength(2);
102
+ expect(unwrap(await store.arrivals({ revision: 2 })).hours[0]?.views).toBe(4);
103
+ });
104
+ /**
105
+ * The invariant the pair of writes exists for: every arrival is in both
106
+ * counters, so a chart drawn off the hours sums to the total drawn beside
107
+ * it.
108
+ */
109
+ it("counts every arrival into the revision's total as well", async () => {
110
+ const store = await counted();
111
+ unwrap(await store.opened([opening(3)], at(13, 5), SKIERS));
112
+ const { hours } = unwrap(await store.arrivals());
113
+ const [total] = unwrap(await store.pageViews());
114
+ expect(hours.reduce((sum, row) => sum + row.views, 0)).toBe(total?.opened);
115
+ expect(total?.opened).toBe(5);
116
+ });
117
+ it("counts nothing at all where the instant is not one", async () => {
118
+ const store = await make();
119
+ const written = await store.opened([opening(2)], "whenever", SKIERS);
120
+ expect(written.ok).toBe(false);
121
+ expect(unwrap(await store.arrivals()).hours).toEqual([]);
122
+ expect(unwrap(await store.pageViews())).toEqual([]);
123
+ });
124
+ it("writes nothing for a delivery that opened nothing", async () => {
125
+ const store = await make();
126
+ unwrap(await store.opened([], at(9), SKIERS));
127
+ expect(unwrap(await store.arrivals()).hours).toEqual([]);
128
+ });
129
+ describe("over a range", () => {
130
+ const spread = async () => {
131
+ const store = await make();
132
+ for (const hour of [1, 5, 9]) {
133
+ unwrap(await store.opened([opening(hour)], at(hour), SKIERS));
134
+ }
135
+ return store;
136
+ };
137
+ it("holds the hours from the start of the range to the end, and not the ends' neighbours", async () => {
138
+ const store = await spread();
139
+ const { hours } = unwrap(await store.arrivals({ from: MIDNIGHT + 5 * HOUR, to: MIDNIGHT + 9 * HOUR }));
140
+ expect(hours.map((row) => row.views)).toEqual([5]);
141
+ });
142
+ it("is unbounded on a side the request leaves out", async () => {
143
+ const store = await spread();
144
+ expect(unwrap(await store.arrivals({ to: MIDNIGHT + 9 * HOUR })).hours).toHaveLength(2);
145
+ expect(unwrap(await store.arrivals({ from: MIDNIGHT + 5 * HOUR })).hours).toHaveLength(2);
146
+ });
147
+ it("answers an empty range with no hours and the beginning still named", async () => {
148
+ const store = await spread();
149
+ const read = unwrap(await store.arrivals({ from: MIDNIGHT + 20 * HOUR, to: MIDNIGHT + 21 * HOUR }));
150
+ expect(read.hours).toEqual([]);
151
+ expect(read.begins).toBe(MIDNIGHT + HOUR);
152
+ });
153
+ });
154
+ describe("the hour counting began", () => {
155
+ it("is the earliest hour the scope has, whatever range was asked for", async () => {
156
+ const store = await make();
157
+ unwrap(await store.opened([opening(1)], at(9), SKIERS));
158
+ unwrap(await store.opened([opening(1)], at(2), SKIERS));
159
+ const read = unwrap(await store.arrivals({ from: MIDNIGHT + 9 * HOUR, to: MIDNIGHT + 10 * HOUR }));
160
+ expect(read.begins).toBe(MIDNIGHT + 2 * HOUR);
161
+ });
162
+ it("is absent where nothing has ever been counted", async () => {
163
+ const store = await make();
164
+ expect(unwrap(await store.arrivals()).begins).toBeUndefined();
165
+ });
166
+ it("narrows with the request, so a page says when it began rather than when the deployment did", async () => {
167
+ const store = await make();
168
+ unwrap(await store.opened([opening(1)], at(2), SKIERS));
169
+ unwrap(await store.opened([opening(1, { treeId: OTHER_TREE })], at(9), SKIERS));
170
+ expect(unwrap(await store.arrivals({ treeId: OTHER_TREE })).begins).toBe(MIDNIGHT + 9 * HOUR);
171
+ });
172
+ });
173
+ it("is not changed by being read", async () => {
174
+ const store = await counted();
175
+ expect(unwrap(await store.arrivals()).hours[0]?.views).toBe(2);
176
+ expect(unwrap(await store.arrivals()).hours[0]?.views).toBe(2);
177
+ });
178
+ });
179
+ };
180
+ //# sourceMappingURL=arrivals.contract.js.map