@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
@@ -1,5 +1,7 @@
1
1
  import type { NodeId, TreeId } from "../ids.js";
2
2
  import type { PrimitiveType } from "../primitive-type.js";
3
+ import type { ActedHourCount } from "./acted.js";
4
+ import type { FunnelHourCount } from "./funnel-hours.js";
3
5
  import type { RevisionViews } from "./page-views.js";
4
6
  import type { ReaderSignalBatch, ReaderSignalKind } from "./signal.js";
5
7
  /**
@@ -91,6 +93,22 @@ export type ReaderTally = {
91
93
  /** One end of a funnel: a node, and what a reader has to have done to it. */
92
94
  export type FunnelEnd = {
93
95
  readonly nodeId: NodeId;
96
+ /**
97
+ * What a reader has to have done to the node, as one of the five kinds.
98
+ *
99
+ * Four of them are the kind itself: a view satisfies this end if it reported
100
+ * a signal of this kind about this node. `disclosed` is the one kind whose
101
+ * signal reports two different things a reader did — it opened the part, or
102
+ * it shut it — and **an end of that kind is the opening** (0424).
103
+ *
104
+ * A shutting is still counted everywhere else it is counted: it is a signal
105
+ * about the part, so the part's `views` holds the page view, and it is a
106
+ * reader using something inside a region, so the region's `engaged` holds it
107
+ * too. What it is not is the thing a question about a disclosure asks about.
108
+ * *Of the views that reached the pricing band, how many opened the terms* is
109
+ * a question; *how many shut the terms they never opened* is not one anybody
110
+ * asks, and it was the difference between the two answers.
111
+ */
94
112
  readonly kind: ReaderSignalKind;
95
113
  };
96
114
  /**
@@ -110,6 +128,22 @@ export type FunnelEnd = {
110
128
  export type FunnelPair = {
111
129
  readonly from: FunnelEnd;
112
130
  readonly to: FunnelEnd;
131
+ /**
132
+ * The pages it is asked on, or absent for every page the window holds.
133
+ *
134
+ * A counter row is already per tree and revision, so this changes nothing
135
+ * about what an answer means — it decides which answers are written at all.
136
+ * Absent is the shape every pair had before a scope existed, and still the
137
+ * right one for a deployment asking about a part wherever it stands: a page
138
+ * where neither end was reported answers nought of nought, which is true.
139
+ *
140
+ * **A page named here that the pair's parts are not on is not a fault.** It
141
+ * answers nought because nothing did either end there, which is the same
142
+ * answer a page nobody opened gives. What the scope buys is the converse — a
143
+ * deployment that asked about two pages does not get a row per page in the
144
+ * window, each saying nought about a question nobody asked there.
145
+ */
146
+ readonly pages?: readonly TreeId[];
113
147
  };
114
148
  export type FunnelAnswer = {
115
149
  readonly treeId: TreeId;
@@ -123,6 +157,21 @@ export type FunnelAnswer = {
123
157
  export type Rollup = {
124
158
  readonly tallies: readonly ReaderTally[];
125
159
  readonly funnels: readonly FunnelAnswer[];
160
+ /**
161
+ * The same answers, cut into the hours the views in each of them entered the
162
+ * funnel (`funnel-hours.ts`).
163
+ *
164
+ * **A partition of each answer's reach rather than a second measurement.**
165
+ * Every view that satisfied a pair's first end is filed under exactly one
166
+ * hour — the earliest hour this window saw it do so — so these rows sum to
167
+ * the answers above, per pair, per revision, for every window folded since
168
+ * the table existed. `rollup.test.ts` asserts the sum.
169
+ *
170
+ * Short by the views only undated batches reported, which is the same
171
+ * shortfall {@link Rollup.undated} reports for the hourly part counter, and
172
+ * empty for every caller that composes batches by hand.
173
+ */
174
+ readonly funnelHours: readonly FunnelHourCount[];
126
175
  /** Distinct page views seen, across every tree and revision in the input. */
127
176
  readonly views: number;
128
177
  /**
@@ -174,12 +223,75 @@ export type Rollup = {
174
223
  * every run is a retry loop somebody should find.
175
224
  */
176
225
  readonly redelivered: number;
226
+ /**
227
+ * The same occurrences as the tallies' three delegated kinds, filed under the
228
+ * hour the door received them in (`acted.ts`).
229
+ *
230
+ * **A slice of the tallies rather than a second measurement**, and it comes
231
+ * out of this one pass for that reason: the repeat refusal above is a
232
+ * judgement made once per batch, and a second walk grouping by hour would
233
+ * make it twice against a different grouping — so an hour's rows would stop
234
+ * summing to the tally they slice, permanently and invisibly (0158).
235
+ * `rollup.test.ts` asserts the sum.
236
+ *
237
+ * Empty where no batch carried a receive instant, which is every caller that
238
+ * composes batches by hand; {@link Rollup.undated} says how many.
239
+ */
240
+ readonly acted: readonly ActedHourCount[];
241
+ /**
242
+ * Batches that carried no instant the door received them at, so their
243
+ * occurrences are in the tallies and in no hour.
244
+ *
245
+ * The same shape of report as {@link Rollup.uncorrelated} and for the same
246
+ * reason: one counter cannot be written honestly and the number is a fact
247
+ * about the input rather than about readers. A window read from either
248
+ * journal always carries one — both stamp it on the way in — so this is
249
+ * non-nought only for batches somebody composed, and a run that reports some
250
+ * is a run whose hourly rows are short by that many batches' worth.
251
+ */
252
+ readonly undated: number;
177
253
  };
178
254
  export declare const EMPTY_ROLLUP: Rollup;
255
+ /**
256
+ * One question, and the pages it is asked on: `null` for every page the window
257
+ * holds.
258
+ *
259
+ * The `pair` here carries the two ends and **never** a scope, because a scope
260
+ * is not part of what a counter row means: `funnelKey` is the revision and the
261
+ * two ends, so the row a scoped question writes and the row an unscoped one
262
+ * writes are the same row.
263
+ */
264
+ export type FunnelQuestion = {
265
+ readonly pair: FunnelPair;
266
+ readonly pages: ReadonlySet<TreeId> | null;
267
+ };
268
+ /**
269
+ * The questions a list of pairs asks, one per pair of ends, with the scopes of
270
+ * the pairs that ask the same question unioned.
271
+ *
272
+ * **This is the defence against a double count, and it is not hypothetical.**
273
+ * A counter row is keyed by the revision and the two ends and applying is
274
+ * additive (0147), so two pairs with the same ends in one `pairs` list write
275
+ * two answers to one row and the store adds them: every figure in that funnel
276
+ * doubled, permanently, with nothing to say it happened (0158). It took a
277
+ * caller deriving its pairs from a list rather than typing them — a project
278
+ * whose goals name the same part and kind twice is enough — for that to stop
279
+ * being a thing nobody would write by hand.
280
+ *
281
+ * **An unscoped pair absorbs a scoped one**, because the two together say *ask
282
+ * this everywhere* and *ask this on page A*, and everywhere includes page A.
283
+ * The alternative — the narrower scope winning — would silently drop pages a
284
+ * deployment did ask about.
285
+ */
286
+ export declare const funnelQuestionsOf: (pairs: readonly FunnelPair[]) => readonly FunnelQuestion[];
179
287
  export type RollupOptions = {
180
288
  /**
181
289
  * The funnels this deployment asked for. Absent means none: a pair is a
182
290
  * question somebody wrote down, and a rollup does not invent questions.
291
+ *
292
+ * Two pairs asking the same question are one question here, however they
293
+ * were scoped — see {@link funnelQuestionsOf}, which is what makes a derived
294
+ * list of pairs safe to hand in.
183
295
  */
184
296
  readonly pairs?: readonly FunnelPair[];
185
297
  };
@@ -202,5 +314,19 @@ export type RollupOptions = {
202
314
  * window's rollup twice still doubles it, because that is two runs rather than
203
315
  * two batches, and nothing here can see the other run.
204
316
  */
205
- export declare const rollUp: (batches: readonly ReaderSignalBatch[], options?: RollupOptions) => Rollup;
317
+ /**
318
+ * A batch as a buffer holds it: with the instant **the door** received it.
319
+ *
320
+ * Optional, because a caller may compose a batch by hand — a backfill, a
321
+ * fixture, a test — and because it is the only field here that does not come
322
+ * off the wire. Where it is absent the batch is counted into the tallies like
323
+ * any other and into no hour, and {@link Rollup.undated} says so.
324
+ *
325
+ * It is `receivedAt` and never `sentAt`: a sender's clock is a number a page
326
+ * said, and a chart drawn from it is a chart a page can move bars on (0355).
327
+ */
328
+ export type DatedBatch = ReaderSignalBatch & {
329
+ readonly receivedAt?: string;
330
+ };
331
+ export declare const rollUp: (batches: readonly DatedBatch[], options?: RollupOptions) => Rollup;
206
332
  //# sourceMappingURL=rollup.d.ts.map
@@ -1,10 +1,14 @@
1
+ import { arrivalHourOf } from "./arrivals.js";
1
2
  export const EMPTY_ROLLUP = {
2
3
  tallies: [],
3
4
  funnels: [],
5
+ funnelHours: [],
4
6
  views: 0,
5
7
  appearances: [],
6
8
  uncorrelated: 0,
7
9
  redelivered: 0,
10
+ acted: [],
11
+ undated: 0,
8
12
  };
9
13
  /**
10
14
  * Where a signal says it happened, or nothing when it does not say.
@@ -17,6 +21,24 @@ const withinOf = (signal) => (signal.kind === "activated" || signal.kind === "di
17
21
  signal.within !== undefined
18
22
  ? signal.within
19
23
  : [];
24
+ /**
25
+ * Whether this signal puts its page view into an end of its own kind.
26
+ *
27
+ * Every signal does, except a `disclosed` that **shut** the part: an end of
28
+ * that kind is the opening (0424), and the two were one end set until this
29
+ * existed. A reader who opened a part and shut it again is in the end set from
30
+ * the open, so what the old rule added was exactly the views that shut a part
31
+ * they never opened — a region a page served already open, and a reader who
32
+ * tidied it away without ever reading it. Those arrived in the end set of a
33
+ * question about *opening* it, and `Goals` draws that question from a goal
34
+ * whose own words are *opens it*.
35
+ *
36
+ * Spelled as a predicate rather than inline so the one rule is in one place:
37
+ * the end sets are what both ends of every pair are answered out of
38
+ * ({@link answerFor}), so a `from` and a `to` can never disagree about what
39
+ * their kind means.
40
+ */
41
+ const satisfiesAnEnd = (signal) => signal.kind !== "disclosed" || signal.open;
20
42
  /**
21
43
  * What joins the parts of every composite key in this module.
22
44
  *
@@ -125,6 +147,35 @@ const accumulatorFor = (into, batch, nodeId, type) => {
125
147
  * about before it has seen the batches.
126
148
  */
127
149
  const endKey = (treeId, revision, nodeId, kind) => `${revisionKey(treeId, revision)}${SEP}${nodeId}${SEP}${kind}`;
150
+ /**
151
+ * The hourly accumulator for one part in one hour, created on first sight.
152
+ *
153
+ * Keyed by the revision, the node **and** the hour, so a part a reader pressed
154
+ * either side of an hour boundary is two rows rather than one — which is the
155
+ * whole point of the counter and the one way its key differs from a tally's.
156
+ */
157
+ const actingFor = (into, batch, nodeId, type, hour) => {
158
+ const key = `${revisionKey(batch.treeId, batch.revision)}${SEP}${nodeId}${SEP}${hour}`;
159
+ const existing = into.get(key);
160
+ if (existing !== undefined) {
161
+ /** The later reading of a node's type wins, exactly as it does on a tally. */
162
+ existing.type = type;
163
+ return existing;
164
+ }
165
+ const fresh = {
166
+ treeId: batch.treeId,
167
+ revision: batch.revision,
168
+ nodeId,
169
+ hour,
170
+ type,
171
+ activations: 0,
172
+ opens: 0,
173
+ closes: 0,
174
+ completions: 0,
175
+ };
176
+ into.set(key, fresh);
177
+ return fresh;
178
+ };
128
179
  const tallyOf = (accumulating) => ({
129
180
  treeId: accumulating.treeId,
130
181
  revision: accumulating.revision,
@@ -139,34 +190,114 @@ const tallyOf = (accumulating) => ({
139
190
  closes: accumulating.closes,
140
191
  completions: accumulating.completions,
141
192
  });
193
+ const endIn = (end) => `${end.nodeId}${SEP}${end.kind}`;
194
+ const pairKey = (pair) => `${endIn(pair.from)}${SEP}${endIn(pair.to)}`;
195
+ /**
196
+ * The questions a list of pairs asks, one per pair of ends, with the scopes of
197
+ * the pairs that ask the same question unioned.
198
+ *
199
+ * **This is the defence against a double count, and it is not hypothetical.**
200
+ * A counter row is keyed by the revision and the two ends and applying is
201
+ * additive (0147), so two pairs with the same ends in one `pairs` list write
202
+ * two answers to one row and the store adds them: every figure in that funnel
203
+ * doubled, permanently, with nothing to say it happened (0158). It took a
204
+ * caller deriving its pairs from a list rather than typing them — a project
205
+ * whose goals name the same part and kind twice is enough — for that to stop
206
+ * being a thing nobody would write by hand.
207
+ *
208
+ * **An unscoped pair absorbs a scoped one**, because the two together say *ask
209
+ * this everywhere* and *ask this on page A*, and everywhere includes page A.
210
+ * The alternative — the narrower scope winning — would silently drop pages a
211
+ * deployment did ask about.
212
+ */
213
+ export const funnelQuestionsOf = (pairs) => {
214
+ const asked = new Map();
215
+ for (const pair of pairs) {
216
+ const key = pairKey(pair);
217
+ const held = asked.get(key);
218
+ const scope = pair.pages === undefined ? null : new Set(pair.pages);
219
+ if (held === undefined) {
220
+ asked.set(key, { pair: { from: pair.from, to: pair.to }, pages: scope });
221
+ continue;
222
+ }
223
+ if (held.pages === null)
224
+ continue;
225
+ if (scope === null)
226
+ held.pages = null;
227
+ else
228
+ for (const page of scope)
229
+ held.pages.add(page);
230
+ }
231
+ return [...asked.values()].map(({ pair, pages }) => ({ pair, pages }));
232
+ };
233
+ /**
234
+ * Record that a view satisfied an end, keeping the **earliest** hour it did.
235
+ *
236
+ * The minimum rather than the first one seen, because a window is a list of
237
+ * batches in whatever order the journal returned them: filing a cohort under
238
+ * *the hour of whichever delivery came back first* would make an hourly row
239
+ * move on a re-read of the same window. An undated delivery never displaces an
240
+ * hour, and a view reported only by undated deliveries has none — it counts in
241
+ * the answer and in no hour, which is what `Rollup.undated` already says.
242
+ */
243
+ const reachedIn = (ends, key, view, hour) => {
244
+ const end = ends.get(key);
245
+ if (end === undefined) {
246
+ ends.set(key, new Map([[view, hour]]));
247
+ return;
248
+ }
249
+ if (!end.has(view)) {
250
+ end.set(view, hour);
251
+ return;
252
+ }
253
+ if (hour === undefined)
254
+ return;
255
+ const held = end.get(view);
256
+ if (held === undefined || hour < held)
257
+ end.set(view, hour);
258
+ };
142
259
  const answerFor = (pair, treeId, revision, ends) => {
143
260
  const from = ends.get(endKey(treeId, revision, pair.from.nodeId, pair.from.kind));
144
261
  const to = ends.get(endKey(treeId, revision, pair.to.nodeId, pair.to.kind));
145
262
  const reached = from?.size ?? 0;
146
263
  const converted = from === undefined || to === undefined
147
264
  ? 0
148
- : [...from].reduce((count, view) => (to.has(view) ? count + 1 : count), 0);
265
+ : [...from.keys()].reduce((count, view) => (to.has(view) ? count + 1 : count), 0);
149
266
  return { treeId, revision, pair, reached, converted };
150
267
  };
151
268
  /**
152
- * Fold a window of stored batches into the counters that outlive them.
269
+ * The same answer, cut into the hours the views in it entered the funnel
270
+ * (`funnel-hours.ts`).
153
271
  *
154
- * Batches from different trees and revisions may be mixed, because a window
155
- * read from the journal is. They are kept apart: a signal about "the fourth
156
- * section" means nothing once a proposal has moved it, and adding two revisions
157
- * of a node together is exactly the mistake that makes *before versus after a
158
- * change* unreadable.
272
+ * **A partition of the reach rather than a filing per delivery**, which is the
273
+ * one property that makes an hourly distinct count honest: every view that
274
+ * reached the first end is in exactly one hour here, so these rows sum to
275
+ * {@link answerFor}'s `reached` and `converted` for this window exactly. A view
276
+ * that converted in a later hour than it reached in is in its **reach** hour on
277
+ * both numbers, so `converted` is never above `reached` in a row and an hour's
278
+ * rate is a rate.
159
279
  *
160
- * **A batch delivered twice is folded once**, where it carries a view key, and
161
- * the repeats are reported as {@link Rollup.redelivered}. The guarantee is
162
- * exactly as wide as the window: two deliveries of one batch that land either
163
- * side of a collection boundary are two windows' input and are counted twice,
164
- * bounded by *(retry delay ÷ window length)* — the same shape of bound already
165
- * stated for the page views that straddle one (0147), and shrinking with the
166
- * same setting. The one-operation rule is untouched (0158): applying one
167
- * window's rollup twice still doubles it, because that is two runs rather than
168
- * two batches, and nothing here can see the other run.
280
+ * Hours nobody entered the funnel in are not rows: this counter is bounded by
281
+ * what readers did, like the hourly part counter beside it, while the answer
282
+ * above is written at nought because a deployment asked the question.
169
283
  */
284
+ const hoursFor = (pair, treeId, revision, ends) => {
285
+ const from = ends.get(endKey(treeId, revision, pair.from.nodeId, pair.from.kind));
286
+ if (from === undefined)
287
+ return [];
288
+ const to = ends.get(endKey(treeId, revision, pair.to.nodeId, pair.to.kind));
289
+ const cohorts = new Map();
290
+ for (const [view, hour] of from) {
291
+ if (hour === undefined)
292
+ continue;
293
+ const standing = cohorts.get(hour) ?? { reached: 0, converted: 0 };
294
+ cohorts.set(hour, {
295
+ reached: standing.reached + 1,
296
+ converted: standing.converted + (to !== undefined && to.has(view) ? 1 : 0),
297
+ });
298
+ }
299
+ return [...cohorts].map(([hour, counts]) => ({ treeId, revision, pair, hour, ...counts }));
300
+ };
170
301
  export const rollUp = (batches, options = {}) => {
171
302
  const accumulators = new Map();
172
303
  const ends = new Map();
@@ -189,8 +320,16 @@ export const rollUp = (batches, options = {}) => {
189
320
  * batch, so the fold stays linear in the signals it was handed (rule 4).
190
321
  */
191
322
  const taken = new Set();
323
+ /**
324
+ * The hourly slice, keyed by revision, node and hour (`acted.ts`).
325
+ *
326
+ * One more map over the same pass rather than a second walk, so the repeat
327
+ * refusal below is made once for both outputs.
328
+ */
329
+ const acting = new Map();
192
330
  let uncorrelated = 0;
193
331
  let redelivered = 0;
332
+ let undated = 0;
194
333
  for (const batch of batches) {
195
334
  const { view } = batch;
196
335
  if (view === undefined)
@@ -211,6 +350,14 @@ export const rollUp = (batches, options = {}) => {
211
350
  }
212
351
  taken.add(identity);
213
352
  }
353
+ /**
354
+ * The hour this delivery's actions are filed under, read once per batch:
355
+ * every signal in it arrived at the same instant, so parsing per signal
356
+ * would be the same answer at ten times the cost.
357
+ */
358
+ const hour = batch.receivedAt === undefined ? undefined : arrivalHourOf(batch.receivedAt);
359
+ if (hour === undefined)
360
+ undated += 1;
214
361
  const key = revisionKey(batch.treeId, batch.revision);
215
362
  const touched = revisions.get(key);
216
363
  const seen = touched ?? {
@@ -236,6 +383,28 @@ export const rollUp = (batches, options = {}) => {
236
383
  }
237
384
  if (signal.kind === "completed")
238
385
  into.completions += 1;
386
+ /**
387
+ * The same four counters again, under the hour (`acted.ts`).
388
+ *
389
+ * Written here rather than derived afterwards because *here* is where the
390
+ * batch, the signal and the hour are all in hand and where the repeat has
391
+ * already been refused. The three kinds are the delegated ones; `viewed`
392
+ * and `dwelled` are deliberately not sliced by hour, and the module says
393
+ * why at length.
394
+ */
395
+ if (hour !== undefined) {
396
+ const acted = actingFor(acting, batch, signal.nodeId, signal.type, hour);
397
+ if (signal.kind === "activated")
398
+ acted.activations += 1;
399
+ if (signal.kind === "disclosed") {
400
+ if (signal.open)
401
+ acted.opens += 1;
402
+ else
403
+ acted.closes += 1;
404
+ }
405
+ if (signal.kind === "completed")
406
+ acted.completions += 1;
407
+ }
239
408
  if (view === undefined)
240
409
  continue;
241
410
  into.views.add(view);
@@ -253,25 +422,43 @@ export const rollUp = (batches, options = {}) => {
253
422
  for (const region of withinOf(signal)) {
254
423
  accumulatorFor(accumulators, batch, region.nodeId, region.type).engaged.add(view);
255
424
  }
256
- const reaching = endKey(batch.treeId, batch.revision, signal.nodeId, signal.kind);
257
- const end = ends.get(reaching);
258
- if (end === undefined)
259
- ends.set(reaching, new Set([view]));
260
- else
261
- end.add(view);
425
+ if (!satisfiesAnEnd(signal))
426
+ continue;
427
+ reachedIn(ends, endKey(batch.treeId, batch.revision, signal.nodeId, signal.kind), view, hour);
262
428
  }
263
429
  }
264
- const pairs = options.pairs ?? [];
265
- const funnels = [...revisions.values()].flatMap(({ treeId, revision }) => pairs.map((pair) => answerFor(pair, treeId, revision, ends)));
430
+ const asked = funnelQuestionsOf(options.pairs ?? []);
431
+ /**
432
+ * The questions, over the revisions the window touched — folded once for both
433
+ * outputs, so the hourly rows are a cut of the very answers written beside
434
+ * them rather than a second judgement about the same window.
435
+ */
436
+ const answered = [...revisions.values()].flatMap(({ treeId, revision }) => asked.flatMap(({ pair, pages }) => pages === null || pages.has(treeId)
437
+ ? [
438
+ {
439
+ answer: answerFor(pair, treeId, revision, ends),
440
+ hours: hoursFor(pair, treeId, revision, ends),
441
+ },
442
+ ]
443
+ : []));
444
+ const funnels = answered.map(({ answer }) => answer);
266
445
  return {
267
446
  tallies: [...accumulators.values()].map(tallyOf),
268
447
  funnels,
448
+ funnelHours: answered.flatMap(({ hours }) => hours),
269
449
  views: views.size,
270
450
  appearances: [...revisions.values()]
271
451
  .filter(({ views: seen }) => seen.size > 0)
272
452
  .map(({ treeId, revision, views: seen }) => ({ treeId, revision, views: seen.size })),
273
453
  uncorrelated,
274
454
  redelivered,
455
+ /**
456
+ * Rows with nothing on them are dropped, which is what keeps this counter
457
+ * bounded by what readers did: a `viewed` on every part of a page creates
458
+ * an accumulator above and no row here.
459
+ */
460
+ acted: [...acting.values()].filter((row) => row.activations + row.opens + row.closes + row.completions > 0),
461
+ undated,
275
462
  };
276
463
  };
277
464
  //# sourceMappingURL=rollup.js.map