@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,375 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { TreeId } from "../ids.js";
3
+ import { type Result } from "../result.js";
4
+ import type { ReaderSignalStoreError } from "./journal.js";
5
+ import type { RevisionViews } from "./page-views.js";
6
+ import { type Ratio } from "./ratios.js";
7
+ /**
8
+ * **When** readers arrived, which is the one thing every counter in this
9
+ * subsystem had thrown away.
10
+ *
11
+ * `page-views.ts` counts the page views that *began* on a revision — exact,
12
+ * counted once, at the door, from the marker a delivery carries
13
+ * ([0214](../../decisions/0214-where-readers-are-is-a-floored-bucket-counted-at-the-door-and-a-page-view-says-when-it-began.md)).
14
+ * It is one number per revision for all time, so it can answer *how many
15
+ * readers* and can never answer *how many yesterday*. Nothing else could
16
+ * either: a tally keeps no time (rule 5 of `docs/signals.md`), and the only
17
+ * rows with an instant on them are the kept deliveries, which are paged by
18
+ * delivery and bounded by the window a deployment keeps them for (0351). A
19
+ * thirty-day chart read from those is thirty days of rows on every render, and
20
+ * a bar drawn from a capped scan is a **wrong number** rather than a shorter
21
+ * list — which is why `Loom portal` filed for this rather than drawing one.
22
+ *
23
+ * So this is the third thing derived from the same marker, after the opening
24
+ * count and the region bucket: **the same arrivals, filed under the hour they
25
+ * arrived in.** Nothing is sent for it, nothing is stored about anybody, and
26
+ * the browser is not involved — the hour is the instant the door was already
27
+ * stamping every counter this delivery moves.
28
+ *
29
+ * ## Why it is a counter and not a read of the kept deliveries
30
+ *
31
+ * The deliveries could answer it, twice over, and both routes are worse.
32
+ *
33
+ * - **Grouping the kept rows by `view` key** and taking each key's earliest
34
+ * receipt is a scan of the whole kept window, and it is a query *about view
35
+ * keys* — the one value in this seam that exists so a funnel can be
36
+ * correlated inside one page view and for nothing else (0146). A counter that
37
+ * needs no key at all is strictly the safer of the two.
38
+ * - **Counting deliveries per hour** needs neither, and counts a reader who
39
+ * stayed ten minutes as a hundred readers. 0214 refused that shape for the
40
+ * region map and it is refused here for the same reason.
41
+ *
42
+ * And a counter answers for as long as the counters live, where either read
43
+ * answers only for the kept window. **The hour outlives the row it could have
44
+ * been derived from**, which is the one consequence of this worth saying out
45
+ * loud rather than leaving to be noticed: a deployment that keeps deliveries
46
+ * for thirty days can still say how many readers arrived in an hour last year.
47
+ * It names no reader, no place and no page view — it is a count of page views
48
+ * of one revision, which is the figure `page-views.ts` already calls *nowhere
49
+ * and nobody* — but it is a count against a clock, and that is new.
50
+ *
51
+ * ## The hour is the unit
52
+ *
53
+ * Finer is not available and coarser would not serve the screen that asked.
54
+ * A *last 24 hours* chart needs twenty-four bars, so a day bucket cannot draw
55
+ * it; a minute bucket is sixty times the rows for a resolution no reading has
56
+ * ever asked for. A surface wanting days sums hours, which is addition over
57
+ * counts that were each counted once.
58
+ *
59
+ * **The hour is UTC and the bucket is its start instant.** A deployment that
60
+ * draws local time shifts the labels, which is a decision about a reader's
61
+ * screen rather than about a counter; storing an offset would make the same row
62
+ * mean two things in two places.
63
+ *
64
+ * Pure: no store, no clock, no DOM, and no import that reaches a package.
65
+ */
66
+ /** One hour, in milliseconds, which is the bucket every row here is filed in. */
67
+ export declare const ARRIVAL_HOUR_MS = 3600000;
68
+ /**
69
+ * The hour an instant falls in, as the instant that hour began.
70
+ *
71
+ * `undefined` where the argument is not an instant. It is the caller's clock
72
+ * and so should never be, but the alternative to saying so is a bucket of
73
+ * `NaN` in a counter — and a counter row nothing can read is worse than a
74
+ * write that refused.
75
+ */
76
+ export declare const arrivalHourOf: (instant: string) => number | undefined;
77
+ /** Page views that began in one hour, of one revision of one tree. */
78
+ export type ArrivalHourCount = {
79
+ readonly treeId: TreeId;
80
+ readonly revision: number;
81
+ /** The hour they arrived in, as the instant it began (UTC). */
82
+ readonly hour: number;
83
+ /** Page views that *began* in this hour, so a longer visit is not a bigger number. */
84
+ readonly views: number;
85
+ };
86
+ /**
87
+ * An hour's count as the store keeps it. See `StoredTally.audienceId` (0284).
88
+ */
89
+ export type StoredArrivalHour = ArrivalHourCount & {
90
+ readonly audienceId: AudienceId;
91
+ readonly updatedAt: string;
92
+ };
93
+ /**
94
+ * What one delivery adds, which is its openings filed under the hour the door
95
+ * read them in.
96
+ *
97
+ * **It is handed the openings rather than the delivery**, exactly as
98
+ * `regionCountsOf` is and for the same reason: the walk that finds them, and
99
+ * the deduplication that makes a retried opening inside one delivery a single
100
+ * arrival, is `openingsOf` in `page-views.ts`. Three counters derived from one
101
+ * walk cannot disagree about how many readers arrived; three walks would, and
102
+ * the disagreement would surface as an hourly chart whose bars do not sum to
103
+ * the number of page views there were.
104
+ *
105
+ * **The instant is the one every other counter on this delivery is stamped
106
+ * with**, so an hour is never a second opinion about when the delivery was
107
+ * received. A failure rather than an empty list where that instant will not
108
+ * parse: openings written to one counter and not the other would make the two
109
+ * numbers differ for a reason no reading could name.
110
+ */
111
+ export declare const arrivalHoursOf: (openings: readonly RevisionViews[], at: string) => Result<readonly ArrivalHourCount[], ReaderSignalStoreError>;
112
+ /**
113
+ * What a ranged read of the counter hands back.
114
+ *
115
+ * The rows in the range **and** the first hour the scope has any row for, which
116
+ * is two statements and one call. A caller needs both to draw anything honest —
117
+ * a range of thirty days on a deployment that began counting a week ago is
118
+ * seven bars and a sentence, not seven bars and twenty-three empty ones — and a
119
+ * caller that had to ask twice would be the caller that asks once.
120
+ */
121
+ export type StoredArrivals = {
122
+ /** Every hour in the range that has a row, in no particular order. */
123
+ readonly hours: readonly StoredArrivalHour[];
124
+ /**
125
+ * The first hour this scope has ever counted an arrival in, whatever range
126
+ * was asked for.
127
+ *
128
+ * Absent means *nothing has ever been counted here*, which is a different
129
+ * sentence from *nobody arrived in the range you asked about* — the
130
+ * distinction this subsystem keeps everywhere a reading can be empty for two
131
+ * reasons (0309, 0347).
132
+ *
133
+ * It narrows with the request's tree, revision and audience, so *By page* can
134
+ * say when counting began for that page rather than for the deployment.
135
+ */
136
+ readonly begins?: number;
137
+ };
138
+ /**
139
+ * A stretch of time, in milliseconds, closed at the start and open at the end.
140
+ *
141
+ * **An hour belongs to the range that its own start falls in**, which is the
142
+ * one rule here a caller has to hold: a range is a set of buckets rather than a
143
+ * set of instants, so a range running from half past ten holds the eleven
144
+ * o'clock bucket and not the ten o'clock one. {@link arrivalRangeOf} builds
145
+ * ranges that are whole hours, which is what makes the rule invisible — and
146
+ * what makes {@link arrivalRangeBefore} give a period with exactly as many buckets in
147
+ * it.
148
+ */
149
+ export type ArrivalRange = {
150
+ readonly from: number;
151
+ readonly to: number;
152
+ };
153
+ /** One hour of a range, which is one bar. */
154
+ export type ArrivalHour = {
155
+ /** The instant the hour began (UTC). */
156
+ readonly hour: number;
157
+ readonly views: number;
158
+ /**
159
+ * Whether this hour is over and inside the range.
160
+ *
161
+ * The last bar is the one this is for: *the last 24 hours* ends in an hour
162
+ * nobody has finished arriving in, and a screen that drew it like the other
163
+ * twenty-three would show every reader a dip at the right-hand edge that is
164
+ * the clock rather than the traffic. False also where the range itself cuts
165
+ * the hour short, which is what an unaligned range does to its last bucket.
166
+ */
167
+ readonly whole: boolean;
168
+ };
169
+ /**
170
+ * The whole hours ending with the hour an instant falls in.
171
+ *
172
+ * `arrivalRangeOf(now, 24)` is *the last 24 hours*: twenty-three hours that are
173
+ * over and the one in progress. Hour-aligned on both ends, which is what the
174
+ * comparison needs — {@link arrivalRangeBefore} of an aligned range is aligned, so the
175
+ * two periods a change is taken over hold the same number of buckets, and a
176
+ * percentage of two honest counts stays honest.
177
+ */
178
+ export declare const arrivalRangeOf: (now: number, hours: number) => ArrivalRange;
179
+ /**
180
+ * Page views by hour over a range, dense, with the hours this deployment
181
+ * cannot speak for left out rather than drawn as nought.
182
+ */
183
+ export type ArrivalSeries = {
184
+ /** The range this is a series over, as asked for. */
185
+ readonly range: ArrivalRange;
186
+ /**
187
+ * One entry per hour, ascending, from the later of the range's first hour and
188
+ * the hour counting began.
189
+ *
190
+ * Dense: an hour nobody arrived in is `views: 0` and is present, because a
191
+ * chart that omits a quiet hour draws a narrower week. Empty where counting
192
+ * began after the range ended, or where nothing has ever been counted.
193
+ */
194
+ readonly hours: readonly ArrivalHour[];
195
+ /** Page views that began inside the range, which is the sum of the hours above. */
196
+ readonly views: number;
197
+ /**
198
+ * The first hour the scope has ever counted, carried through from the store.
199
+ *
200
+ * A surface says *counting began on the 23rd* with it. Absent means nothing
201
+ * has ever been counted, and the series is then empty for a reason that is
202
+ * not *nobody came*.
203
+ */
204
+ readonly begins?: number;
205
+ /**
206
+ * Whether the range starts before counting did.
207
+ *
208
+ * The reason the series can be shorter than the range asked for, published
209
+ * rather than left to a caller comparing two instants — because the
210
+ * comparison has an edge (counting may have begun inside the range's first
211
+ * hour) and a surface getting it wrong would claim a quiet week.
212
+ */
213
+ readonly clipped: boolean;
214
+ };
215
+ /** What a series may be told besides the rows, which is the one thing a clock knows. */
216
+ export type ArrivalSeriesOptions = {
217
+ /**
218
+ * Now, where a caller has it, so the hour in progress is marked as one.
219
+ *
220
+ * Omitted is a series about a stretch that is over, where every bucket the
221
+ * range covers whole is whole. Handed in rather than read from a clock here
222
+ * for the reason every other instant in this subsystem is: a reading is a
223
+ * pure function of what it was given, so two figures on one screen cannot
224
+ * disagree about when it was taken.
225
+ */
226
+ readonly now?: number;
227
+ };
228
+ /**
229
+ * The hours of a range, as the counter answers for them.
230
+ *
231
+ * Rows are summed into their hour, which is what makes this readable over a
232
+ * scope holding several trees, revisions or audiences: **arrivals add**, because
233
+ * a reader who arrived arrived once whichever form of whichever page they were
234
+ * served (0297, 0299). A caller wanting them apart asks for one tree.
235
+ *
236
+ * Rows outside the range are ignored rather than refused. A store answers the
237
+ * range it was asked for, and a reading that threw on a row it did not expect
238
+ * would be a reading that cannot be given a wider read to narrow — which is
239
+ * exactly what {@link arrivalChangeOf} does with it.
240
+ */
241
+ export declare const arrivalSeriesOf: (stored: StoredArrivals, range: ArrivalRange, options?: ArrivalSeriesOptions) => ArrivalSeries;
242
+ /** One bucket of a dense hourly series, before a reading names what it counted. */
243
+ export type HourlyBucket = {
244
+ readonly hour: number;
245
+ readonly count: number;
246
+ readonly whole: boolean;
247
+ };
248
+ /** A dense series and what it adds up to, which is what a reading dresses. */
249
+ export type HourlyFill = {
250
+ readonly hours: readonly HourlyBucket[];
251
+ readonly total: number;
252
+ readonly clipped: boolean;
253
+ };
254
+ /**
255
+ * The rule every hourly series in this subsystem follows, spelled once.
256
+ *
257
+ * Three readings now draw bars over a range — page views by hour (0356), and
258
+ * what readers did by hour (`acted.ts`), in a series and in a comparison — and
259
+ * the rule they share is not the arithmetic but the **honesty**: an hour with
260
+ * no row is a nought that is drawn, an hour before counting began is not drawn
261
+ * at all, and the hour in progress is marked rather than drawn as a fall. Three
262
+ * spellings of that would be three chances for one chart to claim a quiet week
263
+ * the deployment never had.
264
+ *
265
+ * It is exported rather than private because `acted.ts` is a module and not a
266
+ * function in this one. A reading hands over its rows, the first hour its scope
267
+ * ever counted, the range, and which number on a row it is counting.
268
+ */
269
+ export declare const hourlySeriesOf: <Row extends {
270
+ readonly hour: number;
271
+ }>(rows: readonly Row[], begins: number | undefined, range: ArrivalRange, count: (row: Row) => number, options?: ArrivalSeriesOptions) => HourlyFill;
272
+ /**
273
+ * The stretch of the same length immediately before a range.
274
+ *
275
+ * The period a *page views in the range* figure is compared against, computed
276
+ * here rather than at a call site so that the two ranges a comparison is taken
277
+ * over cannot be of different lengths — which is the one way to make a
278
+ * percentage of two honest counts dishonest.
279
+ */
280
+ export declare const arrivalRangeBefore: (range: ArrivalRange) => ArrivalRange;
281
+ /**
282
+ * Page views in a range against page views in the period before it.
283
+ *
284
+ * The figure the wireframe puts over the whole screen, and the one that is a
285
+ * lie if the earlier period is one the deployment was not counting through.
286
+ */
287
+ export type ArrivalChange = {
288
+ readonly range: ArrivalRange;
289
+ /** The equal-length period the comparison is against, which is {@link arrivalRangeBefore}. */
290
+ readonly before: ArrivalRange;
291
+ readonly views: number;
292
+ /**
293
+ * Page views in the earlier period, or `null` where counting had not begun
294
+ * when it started.
295
+ *
296
+ * `null` is not nought and the difference is the whole of this field: a
297
+ * deployment that upgraded on Tuesday has no arrivals before Tuesday and
298
+ * never had any readers missing either. Reporting nought there would publish
299
+ * *every reader you have is new this week* on every deployment's first month.
300
+ */
301
+ readonly was: number | null;
302
+ /**
303
+ * The quotient, or why there is none (`ratios.ts`).
304
+ *
305
+ * `unmeasured` where the earlier period predates counting, `from-nothing`
306
+ * where it was counted and held no arrivals — which is the rise a surface
307
+ * most wants to draw and could least afford to read as *nothing to compare*.
308
+ */
309
+ readonly ratio: Ratio;
310
+ };
311
+ /**
312
+ * Both figures and the quotient, from one read.
313
+ *
314
+ * The read has to span both periods, which is what `arrivalRangeBefore` is for: a
315
+ * caller asks the store for `{ from: arrivalRangeBefore(range).from, to: range.to }`
316
+ * and hands the result here. Taking two reads would be two scans and a seam
317
+ * where the clock moved between them.
318
+ */
319
+ export declare const arrivalChangeOf: (stored: StoredArrivals, range: ArrivalRange, options?: ArrivalSeriesOptions) => ArrivalChange;
320
+ /**
321
+ * What a surface asks for: a range, the narrowing, and the clock.
322
+ *
323
+ * The three narrowings are the counter read's own, so a chart of one page is
324
+ * this with a `treeId` on it.
325
+ */
326
+ export type ArrivalReadingRequest = {
327
+ readonly range: ArrivalRange;
328
+ /** Absent reads every tree the handle can see, which is the scope rule (0020). */
329
+ readonly treeId?: TreeId;
330
+ /** Absent reads every audience (0284), whose arrivals then add. */
331
+ readonly audience?: AudienceId | undefined;
332
+ /** Absent reads every revision, whose arrivals then add. */
333
+ readonly revision?: number;
334
+ /** Now, where the caller has it, so the hour in progress is marked as one. */
335
+ readonly now?: number;
336
+ };
337
+ /**
338
+ * The one method of the counter handle a reading of this needs.
339
+ *
340
+ * Named rather than written inline so that a reading joining two counters —
341
+ * what readers did, over the page views they did it in (`acted.ts`) — can ask
342
+ * for both halves without respelling either.
343
+ */
344
+ export type ArrivalCounterHandle = {
345
+ readonly arrivals: (request?: {
346
+ readonly treeId?: TreeId;
347
+ readonly audience?: AudienceId | undefined;
348
+ readonly revision?: number;
349
+ readonly from?: number;
350
+ readonly to?: number;
351
+ }) => Promise<Result<StoredArrivals, ReaderSignalStoreError>>;
352
+ };
353
+ /** The chart and the two figures above it, from one read. */
354
+ export type ArrivalReading = {
355
+ readonly series: ArrivalSeries;
356
+ readonly change: ArrivalChange;
357
+ };
358
+ /**
359
+ * The chart, the range's figure and the change on the period before it, in one
360
+ * call against a counter handle.
361
+ *
362
+ * **It exists because the composition has a wrong version that type-checks.**
363
+ * The change is over two periods, so the read has to span both — and a caller
364
+ * who read `{ from: range.from }`, which is the obvious line, would get a
365
+ * comparison whose earlier period is empty **because it was not read** rather
366
+ * than because nobody arrived in it. That reads as *every reader you have is
367
+ * new*, on a screen, from a store that holds the right answer. This takes the
368
+ * range a surface is drawing and derives the read from it, so there is nothing
369
+ * to get wrong.
370
+ *
371
+ * The store handle is narrowed to the one method, so a reading cannot reach a
372
+ * counter it was not asked about.
373
+ */
374
+ export declare const readReaderArrivals: (store: ArrivalCounterHandle, request: ArrivalReadingRequest) => Promise<Result<ArrivalReading, ReaderSignalStoreError>>;
375
+ //# sourceMappingURL=arrivals.d.ts.map
@@ -0,0 +1,254 @@
1
+ import { err, ok } from "../result.js";
2
+ import { ratioOf } from "./ratios.js";
3
+ /**
4
+ * **When** readers arrived, which is the one thing every counter in this
5
+ * subsystem had thrown away.
6
+ *
7
+ * `page-views.ts` counts the page views that *began* on a revision — exact,
8
+ * counted once, at the door, from the marker a delivery carries
9
+ * ([0214](../../decisions/0214-where-readers-are-is-a-floored-bucket-counted-at-the-door-and-a-page-view-says-when-it-began.md)).
10
+ * It is one number per revision for all time, so it can answer *how many
11
+ * readers* and can never answer *how many yesterday*. Nothing else could
12
+ * either: a tally keeps no time (rule 5 of `docs/signals.md`), and the only
13
+ * rows with an instant on them are the kept deliveries, which are paged by
14
+ * delivery and bounded by the window a deployment keeps them for (0351). A
15
+ * thirty-day chart read from those is thirty days of rows on every render, and
16
+ * a bar drawn from a capped scan is a **wrong number** rather than a shorter
17
+ * list — which is why `Loom portal` filed for this rather than drawing one.
18
+ *
19
+ * So this is the third thing derived from the same marker, after the opening
20
+ * count and the region bucket: **the same arrivals, filed under the hour they
21
+ * arrived in.** Nothing is sent for it, nothing is stored about anybody, and
22
+ * the browser is not involved — the hour is the instant the door was already
23
+ * stamping every counter this delivery moves.
24
+ *
25
+ * ## Why it is a counter and not a read of the kept deliveries
26
+ *
27
+ * The deliveries could answer it, twice over, and both routes are worse.
28
+ *
29
+ * - **Grouping the kept rows by `view` key** and taking each key's earliest
30
+ * receipt is a scan of the whole kept window, and it is a query *about view
31
+ * keys* — the one value in this seam that exists so a funnel can be
32
+ * correlated inside one page view and for nothing else (0146). A counter that
33
+ * needs no key at all is strictly the safer of the two.
34
+ * - **Counting deliveries per hour** needs neither, and counts a reader who
35
+ * stayed ten minutes as a hundred readers. 0214 refused that shape for the
36
+ * region map and it is refused here for the same reason.
37
+ *
38
+ * And a counter answers for as long as the counters live, where either read
39
+ * answers only for the kept window. **The hour outlives the row it could have
40
+ * been derived from**, which is the one consequence of this worth saying out
41
+ * loud rather than leaving to be noticed: a deployment that keeps deliveries
42
+ * for thirty days can still say how many readers arrived in an hour last year.
43
+ * It names no reader, no place and no page view — it is a count of page views
44
+ * of one revision, which is the figure `page-views.ts` already calls *nowhere
45
+ * and nobody* — but it is a count against a clock, and that is new.
46
+ *
47
+ * ## The hour is the unit
48
+ *
49
+ * Finer is not available and coarser would not serve the screen that asked.
50
+ * A *last 24 hours* chart needs twenty-four bars, so a day bucket cannot draw
51
+ * it; a minute bucket is sixty times the rows for a resolution no reading has
52
+ * ever asked for. A surface wanting days sums hours, which is addition over
53
+ * counts that were each counted once.
54
+ *
55
+ * **The hour is UTC and the bucket is its start instant.** A deployment that
56
+ * draws local time shifts the labels, which is a decision about a reader's
57
+ * screen rather than about a counter; storing an offset would make the same row
58
+ * mean two things in two places.
59
+ *
60
+ * Pure: no store, no clock, no DOM, and no import that reaches a package.
61
+ */
62
+ /** One hour, in milliseconds, which is the bucket every row here is filed in. */
63
+ export const ARRIVAL_HOUR_MS = 3_600_000;
64
+ /**
65
+ * The hour an instant falls in, as the instant that hour began.
66
+ *
67
+ * `undefined` where the argument is not an instant. It is the caller's clock
68
+ * and so should never be, but the alternative to saying so is a bucket of
69
+ * `NaN` in a counter — and a counter row nothing can read is worse than a
70
+ * write that refused.
71
+ */
72
+ export const arrivalHourOf = (instant) => {
73
+ const at = Date.parse(instant);
74
+ return Number.isFinite(at) ? Math.floor(at / ARRIVAL_HOUR_MS) * ARRIVAL_HOUR_MS : undefined;
75
+ };
76
+ /**
77
+ * What one delivery adds, which is its openings filed under the hour the door
78
+ * read them in.
79
+ *
80
+ * **It is handed the openings rather than the delivery**, exactly as
81
+ * `regionCountsOf` is and for the same reason: the walk that finds them, and
82
+ * the deduplication that makes a retried opening inside one delivery a single
83
+ * arrival, is `openingsOf` in `page-views.ts`. Three counters derived from one
84
+ * walk cannot disagree about how many readers arrived; three walks would, and
85
+ * the disagreement would surface as an hourly chart whose bars do not sum to
86
+ * the number of page views there were.
87
+ *
88
+ * **The instant is the one every other counter on this delivery is stamped
89
+ * with**, so an hour is never a second opinion about when the delivery was
90
+ * received. A failure rather than an empty list where that instant will not
91
+ * parse: openings written to one counter and not the other would make the two
92
+ * numbers differ for a reason no reading could name.
93
+ */
94
+ export const arrivalHoursOf = (openings, at) => {
95
+ if (openings.length === 0)
96
+ return ok([]);
97
+ const hour = arrivalHourOf(at);
98
+ if (hour === undefined) {
99
+ return err({
100
+ code: "unavailable",
101
+ detail: `could not place ${openings.length} page views in an hour: ${at} is not an instant`,
102
+ });
103
+ }
104
+ return ok(openings.map(({ treeId, revision, views }) => ({ treeId, revision, hour, views })));
105
+ };
106
+ /**
107
+ * The whole hours ending with the hour an instant falls in.
108
+ *
109
+ * `arrivalRangeOf(now, 24)` is *the last 24 hours*: twenty-three hours that are
110
+ * over and the one in progress. Hour-aligned on both ends, which is what the
111
+ * comparison needs — {@link arrivalRangeBefore} of an aligned range is aligned, so the
112
+ * two periods a change is taken over hold the same number of buckets, and a
113
+ * percentage of two honest counts stays honest.
114
+ */
115
+ export const arrivalRangeOf = (now, hours) => {
116
+ const current = Math.floor(now / ARRIVAL_HOUR_MS) * ARRIVAL_HOUR_MS;
117
+ return {
118
+ from: current - (Math.max(1, Math.trunc(hours)) - 1) * ARRIVAL_HOUR_MS,
119
+ to: current + ARRIVAL_HOUR_MS,
120
+ };
121
+ };
122
+ const hourAt = (instant) => Math.floor(instant / ARRIVAL_HOUR_MS) * ARRIVAL_HOUR_MS;
123
+ /** The first bucket of a range, which is the first hour that begins inside it. */
124
+ const firstHourOf = (from) => Math.ceil(from / ARRIVAL_HOUR_MS) * ARRIVAL_HOUR_MS;
125
+ /**
126
+ * The hours of a range, as the counter answers for them.
127
+ *
128
+ * Rows are summed into their hour, which is what makes this readable over a
129
+ * scope holding several trees, revisions or audiences: **arrivals add**, because
130
+ * a reader who arrived arrived once whichever form of whichever page they were
131
+ * served (0297, 0299). A caller wanting them apart asks for one tree.
132
+ *
133
+ * Rows outside the range are ignored rather than refused. A store answers the
134
+ * range it was asked for, and a reading that threw on a row it did not expect
135
+ * would be a reading that cannot be given a wider read to narrow — which is
136
+ * exactly what {@link arrivalChangeOf} does with it.
137
+ */
138
+ export const arrivalSeriesOf = (stored, range, options = {}) => {
139
+ const filled = hourlySeriesOf(stored.hours, stored.begins, range, (row) => row.views, options);
140
+ return {
141
+ range,
142
+ hours: filled.hours.map(({ hour, count, whole }) => ({ hour, views: count, whole })),
143
+ views: filled.total,
144
+ ...(stored.begins === undefined ? {} : { begins: stored.begins }),
145
+ clipped: filled.clipped,
146
+ };
147
+ };
148
+ /**
149
+ * The rule every hourly series in this subsystem follows, spelled once.
150
+ *
151
+ * Three readings now draw bars over a range — page views by hour (0356), and
152
+ * what readers did by hour (`acted.ts`), in a series and in a comparison — and
153
+ * the rule they share is not the arithmetic but the **honesty**: an hour with
154
+ * no row is a nought that is drawn, an hour before counting began is not drawn
155
+ * at all, and the hour in progress is marked rather than drawn as a fall. Three
156
+ * spellings of that would be three chances for one chart to claim a quiet week
157
+ * the deployment never had.
158
+ *
159
+ * It is exported rather than private because `acted.ts` is a module and not a
160
+ * function in this one. A reading hands over its rows, the first hour its scope
161
+ * ever counted, the range, and which number on a row it is counting.
162
+ */
163
+ export const hourlySeriesOf = (rows, begins, range, count, options = {}) => {
164
+ const clipped = begins !== undefined && begins > range.from;
165
+ const first = Math.max(firstHourOf(range.from), begins ?? 0);
166
+ const last = hourAt(range.to - 1);
167
+ const counted = new Map();
168
+ for (const row of rows) {
169
+ if (row.hour < range.from || row.hour >= range.to)
170
+ continue;
171
+ counted.set(row.hour, (counted.get(row.hour) ?? 0) + count(row));
172
+ }
173
+ const hours = [];
174
+ if (begins !== undefined) {
175
+ for (let hour = first; hour <= last; hour += ARRIVAL_HOUR_MS) {
176
+ const ends = hour + ARRIVAL_HOUR_MS;
177
+ hours.push({
178
+ hour,
179
+ count: counted.get(hour) ?? 0,
180
+ whole: ends <= range.to && (options.now === undefined || options.now >= ends),
181
+ });
182
+ }
183
+ }
184
+ return {
185
+ hours,
186
+ total: hours.reduce((sum, hour) => sum + hour.count, 0),
187
+ clipped,
188
+ };
189
+ };
190
+ /**
191
+ * The stretch of the same length immediately before a range.
192
+ *
193
+ * The period a *page views in the range* figure is compared against, computed
194
+ * here rather than at a call site so that the two ranges a comparison is taken
195
+ * over cannot be of different lengths — which is the one way to make a
196
+ * percentage of two honest counts dishonest.
197
+ */
198
+ export const arrivalRangeBefore = (range) => ({
199
+ from: range.from - (range.to - range.from),
200
+ to: range.from,
201
+ });
202
+ /**
203
+ * Both figures and the quotient, from one read.
204
+ *
205
+ * The read has to span both periods, which is what `arrivalRangeBefore` is for: a
206
+ * caller asks the store for `{ from: arrivalRangeBefore(range).from, to: range.to }`
207
+ * and hands the result here. Taking two reads would be two scans and a seam
208
+ * where the clock moved between them.
209
+ */
210
+ export const arrivalChangeOf = (stored, range, options = {}) => {
211
+ const before = arrivalRangeBefore(range);
212
+ const now = arrivalSeriesOf(stored, range, options);
213
+ const earlier = arrivalSeriesOf(stored, before, options);
214
+ const was = stored.begins === undefined || stored.begins > before.from ? null : earlier.views;
215
+ return {
216
+ range,
217
+ before,
218
+ views: now.views,
219
+ was,
220
+ ratio: ratioOf(was, now.views),
221
+ };
222
+ };
223
+ /**
224
+ * The chart, the range's figure and the change on the period before it, in one
225
+ * call against a counter handle.
226
+ *
227
+ * **It exists because the composition has a wrong version that type-checks.**
228
+ * The change is over two periods, so the read has to span both — and a caller
229
+ * who read `{ from: range.from }`, which is the obvious line, would get a
230
+ * comparison whose earlier period is empty **because it was not read** rather
231
+ * than because nobody arrived in it. That reads as *every reader you have is
232
+ * new*, on a screen, from a store that holds the right answer. This takes the
233
+ * range a surface is drawing and derives the read from it, so there is nothing
234
+ * to get wrong.
235
+ *
236
+ * The store handle is narrowed to the one method, so a reading cannot reach a
237
+ * counter it was not asked about.
238
+ */
239
+ export const readReaderArrivals = async (store, request) => {
240
+ const { range, now, ...narrowing } = request;
241
+ const read = await store.arrivals({
242
+ ...narrowing,
243
+ from: arrivalRangeBefore(range).from,
244
+ to: range.to,
245
+ });
246
+ if (!read.ok)
247
+ return read;
248
+ const options = now === undefined ? {} : { now };
249
+ return ok({
250
+ series: arrivalSeriesOf(read.value, range, options),
251
+ change: arrivalChangeOf(read.value, range, options),
252
+ });
253
+ };
254
+ //# sourceMappingURL=arrivals.js.map