@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,235 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { audienceScopeRead, readingKeyOf } from "./audiences.js";
3
+ export const CONVERSION_SILENCES = everyMemberOf()([
4
+ "unsplit",
5
+ "unscaled",
6
+ "unopened",
7
+ "uncounted",
8
+ "stale",
9
+ "unanswered",
10
+ "inconsistent",
11
+ ]);
12
+ /**
13
+ * One line per silence, for a surface saying why a page has no funnel figure.
14
+ *
15
+ * **The sentences are the order's own, moved here rather than written again.**
16
+ * Every member of this set is also a {@link ConversionStanding}, and
17
+ * {@link describeConversionStanding} has had a line for each since the order
18
+ * was built — so a second spelling of *no page views counted at the door* would
19
+ * be the thing this subsystem's census of silences exists to stop, one module
20
+ * in. The standing now defers to this for the seven it shares, which is why the
21
+ * text below is unchanged from what that function returned.
22
+ *
23
+ * The condition's own sentence — `describeSilenceCondition` in
24
+ * [`silences.ts`](silences.ts) — is the third and is not a replacement for
25
+ * either: it is the wording shared across every reading here, for a card
26
+ * speaking about two readings at once.
27
+ */
28
+ export const describeConversionSilence = (silence) => {
29
+ switch (silence) {
30
+ case "unsplit":
31
+ return "one window holds two forms of the page and says which readers neither";
32
+ case "unscaled":
33
+ return "no page views counted at the door, so its loss is not comparable with another page's";
34
+ case "unopened":
35
+ return "the page-view row is there and nothing has said a page view began";
36
+ case "uncounted":
37
+ return "readers arrived and no rollup has folded a window of their reading yet";
38
+ case "stale":
39
+ return "every question it is asked names a part this version of the page no longer has";
40
+ case "unanswered":
41
+ return "nobody reached the start of any question it is asked";
42
+ case "inconsistent":
43
+ return "more readers reached its sharpest ask than have ever appeared";
44
+ }
45
+ };
46
+ export const CONVERSION_STANDINGS = everyMemberOf()([
47
+ "ranked",
48
+ "unleaked",
49
+ "unasked",
50
+ "unsplit",
51
+ "unscaled",
52
+ "unopened",
53
+ "uncounted",
54
+ "stale",
55
+ "unanswered",
56
+ "inconsistent",
57
+ ]);
58
+ /** One line per standing, for a surface naming why a page is where it is. */
59
+ export const describeConversionStanding = (standing) => {
60
+ switch (standing) {
61
+ case "ranked":
62
+ return "in the order, by the readers it loses between an ask and its answer";
63
+ case "unleaked":
64
+ return "every reader who reached one of its asks went on to answer it";
65
+ case "unasked":
66
+ return "nothing asks this version of the page for anything";
67
+ default:
68
+ return describeConversionSilence(standing);
69
+ }
70
+ };
71
+ const EMPTY_STANDINGS = Object.freeze(Object.fromEntries(CONVERSION_STANDINGS.map((standing) => [standing, 0])));
72
+ const lostIn = (pair) => pair.reached - pair.converted;
73
+ /**
74
+ * The ask that loses the most readers between its two ends.
75
+ *
76
+ * Over the questions this revision still has, because a question naming a part
77
+ * the page no longer has reports counts that cannot move and noughts that are
78
+ * not reader facts (0212) — so a stale question with a large count would take
79
+ * the head of a page's own order away from a sound one.
80
+ *
81
+ * Ties go to the pair the reading published first, which is a stable order of
82
+ * the two ends rather than an arrival order.
83
+ */
84
+ const sharpestIn = (pairs) => pairs
85
+ .filter((pair) => !pair.stale)
86
+ .reduce((worst, pair) => (worst === null || lostIn(pair) > lostIn(worst) ? pair : worst), null);
87
+ const silenceOfDoor = (reach) => {
88
+ switch (reach.silence) {
89
+ case "unmeasured":
90
+ return "unscaled";
91
+ case "unopened":
92
+ return "unopened";
93
+ case "uncounted":
94
+ return "uncounted";
95
+ case null:
96
+ return null;
97
+ }
98
+ };
99
+ /**
100
+ * One page's row, with the states tried in the order they have to be tried in.
101
+ *
102
+ * The unsplit window first, because it is the cause of the empty pair list
103
+ * underneath it. The door's three next, because a page with no scale has
104
+ * nothing to put a leak on. Then what was asked, because a question that does
105
+ * not exist cannot be answered. Then whether anybody reached an ask, then
106
+ * whether anybody was lost at one — and the disagreement last, because it is a
107
+ * statement about a count and a row together.
108
+ */
109
+ const rowOf = (reach) => {
110
+ const where = {
111
+ treeId: reach.treeId,
112
+ revision: reach.revision,
113
+ audienceId: reach.audienceId,
114
+ opened: reach.silence === "unmeasured" ? null : reach.opened,
115
+ inflation: reach.inflation,
116
+ questions: reach.pairs.length,
117
+ stalePairs: reach.stalePairs,
118
+ };
119
+ const nothing = { at: null, lost: null, readers: null, readersAtLeast: null, rate: null };
120
+ if (audienceScopeRead(reach).reading === "mixed") {
121
+ return { ...where, ...nothing, standing: "unsplit" };
122
+ }
123
+ const door = silenceOfDoor(reach);
124
+ if (door !== null)
125
+ return { ...where, ...nothing, standing: door };
126
+ if (reach.pairs.length === 0)
127
+ return { ...where, ...nothing, standing: "unasked" };
128
+ const at = sharpestIn(reach.pairs);
129
+ if (at === null)
130
+ return { ...where, ...nothing, standing: "stale" };
131
+ if (at.reached === 0)
132
+ return { ...where, ...nothing, standing: "unanswered" };
133
+ const lost = lostIn(at);
134
+ const carried = { at, lost, rate: at.rate };
135
+ const unscaled = { readers: null, readersAtLeast: null };
136
+ if (lost === 0)
137
+ return { ...where, ...carried, ...unscaled, standing: "unleaked" };
138
+ /**
139
+ * A reading whose counts cannot be reconciled with the page views there were
140
+ * to hold them keeps its counts and loses its scale, which is the half of the
141
+ * row that is not true — and the pair withholds its leak on exactly those
142
+ * terms, so the absent interval is the check rather than a second spelling of
143
+ * it. The door's three are already past, so a pair this far in has a leak
144
+ * unless its counts and its row disagree.
145
+ */
146
+ if (at.leak === null) {
147
+ return { ...where, ...carried, ...unscaled, standing: "inconsistent" };
148
+ }
149
+ return {
150
+ ...where,
151
+ ...carried,
152
+ readers: at.leak.atMost,
153
+ readersAtLeast: at.leak.atLeast,
154
+ standing: "ranked",
155
+ };
156
+ };
157
+ /**
158
+ * The worse of two, which is the ranking rule spelled once.
159
+ *
160
+ * By readers lost before rate, for the reason a page ranks its own falls that
161
+ * way (0221): two readers out of three who left an ask unanswered is a worse
162
+ * rate and a smaller problem than four hundred out of a thousand.
163
+ */
164
+ const worseOf = (one, other) => (other.readers ?? 0) - (one.readers ?? 0) ||
165
+ (one.rate ?? 1) - (other.rate ?? 1) ||
166
+ one.treeId.localeCompare(other.treeId) ||
167
+ other.revision - one.revision;
168
+ /**
169
+ * Whether the head of the order is beyond the straddle's reach.
170
+ *
171
+ * The ranked rows are sorted by their ceilings, so the only page that can
172
+ * overtake the head is the one immediately after it: nothing further down has a
173
+ * higher ceiling to do it with. One comparison answers the whole order.
174
+ *
175
+ * The two `null` checks are the narrowing rather than a case — a ranked row
176
+ * carries both ends of its interval or it is not ranked — and they are written
177
+ * out so that a row which somehow lacks one is reported as *not secure* rather
178
+ * than as secure by a default.
179
+ */
180
+ const headSecure = (ranked) => {
181
+ const [head, next] = ranked;
182
+ if (head === undefined)
183
+ return null;
184
+ if (next === undefined)
185
+ return true;
186
+ return head.readersAtLeast !== null && next.readers !== null && head.readersAtLeast >= next.readers;
187
+ };
188
+ /** Tree id, then newest revision first, then form — the order the readings are published in. */
189
+ const byPage = (one, other) => one.treeId.localeCompare(other.treeId) ||
190
+ other.revision - one.revision ||
191
+ (one.audienceId ?? "").localeCompare(other.audienceId ?? "");
192
+ /**
193
+ * A deployment's pages, in the order their funnels should be looked at.
194
+ *
195
+ * ```ts
196
+ * const assembly = windowAssemblyOf(window, context)
197
+ * const order = deploymentConversionOf(windowFunnelsOf(window, assembly).pages)
198
+ * ```
199
+ *
200
+ * Takes the funnel answers rather than the counters, for the reason every
201
+ * derived reading in this subsystem takes readings: each answer is separately
202
+ * useful and separately drawn, and deriving one twice is how two screens come
203
+ * to disagree about one page.
204
+ */
205
+ export const deploymentConversionOf = (funnels) => {
206
+ const seen = new Set();
207
+ const read = [];
208
+ let duplicated = 0;
209
+ for (const reach of funnels) {
210
+ const key = readingKeyOf(reach);
211
+ if (seen.has(key)) {
212
+ duplicated += 1;
213
+ continue;
214
+ }
215
+ seen.add(key);
216
+ read.push(rowOf(reach));
217
+ }
218
+ const ranked = read.filter((row) => row.standing === "ranked").sort(worseOf);
219
+ const standings = { ...EMPTY_STANDINGS };
220
+ for (const row of read)
221
+ standings[row.standing] += 1;
222
+ return {
223
+ ranked,
224
+ unranked: read.filter((row) => row.standing !== "ranked").sort(byPage),
225
+ worst: ranked[0] ?? null,
226
+ worstSecure: headSecure(ranked),
227
+ standings,
228
+ trees: new Set(read.map((row) => row.treeId)).size,
229
+ arrivals: read.reduce((sum, row) => sum + (row.opened ?? 0), 0),
230
+ questions: read.reduce((sum, row) => sum + row.questions, 0),
231
+ stalePairs: read.reduce((sum, row) => sum + row.stalePairs, 0),
232
+ duplicated,
233
+ };
234
+ };
235
+ //# sourceMappingURL=conversion.js.map
@@ -0,0 +1,24 @@
1
+ /**
2
+ * The sixth contract suite both reader-signal journals are run against: **the
3
+ * deliveries of one page view, read on the key and on nothing else** (0355).
4
+ *
5
+ * It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
6
+ * for the reason `kept.contract.ts` and `applied-window.contract.ts` are: that
7
+ * directory is another lane's and this is reader-signal work. The finding filed
8
+ * with 0316 asks for the set to be moved together, which is one import away.
9
+ *
10
+ * **Every property here needs two implementations to be worth asserting.** The
11
+ * key is a nullable column in Postgres and an absent field in memory, which is
12
+ * exactly the shape that makes two stores quietly disagree — the same
13
+ * difference `kept.contract.ts` exists for one column over. Two of these
14
+ * assertions are about what the narrowing must *not* match — a delivery of
15
+ * another page view, and a delivery that names none at all — and the second is
16
+ * the one that goes wrong by accident: in Postgres `view = $1` cannot match a
17
+ * null, and in memory the field is absent, so a comparison written the obvious
18
+ * way would gather every uncorrelated delivery into whichever page view asked.
19
+ * (The application scope is not here, because the memory store takes none; it
20
+ * is `scoped.test.ts`'s, beside the other reads it covers.)
21
+ */
22
+ import type { ReaderSignalJournal } from "./journal.js";
23
+ export declare const describeCorrelatedDeliveryContract: (name: string, make: () => Promise<ReaderSignalJournal> | ReaderSignalJournal) => void;
24
+ //# sourceMappingURL=correlated.contract.d.ts.map
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The sixth contract suite both reader-signal journals are run against: **the
3
+ * deliveries of one page view, read on the key and on nothing else** (0355).
4
+ *
5
+ * It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
6
+ * for the reason `kept.contract.ts` and `applied-window.contract.ts` are: that
7
+ * directory is another lane's and this is reader-signal work. The finding filed
8
+ * with 0316 asks for the set to be moved together, which is one import away.
9
+ *
10
+ * **Every property here needs two implementations to be worth asserting.** The
11
+ * key is a nullable column in Postgres and an absent field in memory, which is
12
+ * exactly the shape that makes two stores quietly disagree — the same
13
+ * difference `kept.contract.ts` exists for one column over. Two of these
14
+ * assertions are about what the narrowing must *not* match — a delivery of
15
+ * another page view, and a delivery that names none at all — and the second is
16
+ * the one that goes wrong by accident: in Postgres `view = $1` cannot match a
17
+ * null, and in memory the field is absent, so a comparison written the obvious
18
+ * way would gather every uncorrelated delivery into whichever page view asked.
19
+ * (The application scope is not here, because the memory store takes none; it
20
+ * is `scoped.test.ts`'s, beside the other reads it covers.)
21
+ */
22
+ import { describe, expect, it } from "vitest";
23
+ import { batchOf, viewed, viewKey } from "../testing/reader-signal-contract.js";
24
+ const unwrap = (result) => {
25
+ if (!result.ok)
26
+ throw new Error(result.error.detail);
27
+ return result.value;
28
+ };
29
+ export const describeCorrelatedDeliveryContract = (name, make) => {
30
+ describe(`${name} — the deliveries of one page view`, () => {
31
+ const ONE = viewKey(1);
32
+ const TWO = viewKey(2);
33
+ /**
34
+ * Two page views and a delivery belonging to neither, interleaved, because
35
+ * a filter that read the newest run of rows rather than the matching ones
36
+ * would pass against a table where each page view's deliveries are
37
+ * adjacent.
38
+ */
39
+ const mixed = async () => {
40
+ const journal = await make();
41
+ await journal.receive([
42
+ batchOf([viewed("a")], { view: ONE, first: true }),
43
+ batchOf([viewed("b")], { view: TWO, first: true }),
44
+ batchOf([viewed("c")]),
45
+ batchOf([viewed("d")], { view: ONE }),
46
+ ]);
47
+ return journal;
48
+ };
49
+ const names = async (journal, view) => unwrap(await journal.read(view === undefined ? undefined : { view })).batches.map((batch) => batch.signals[0]?.nodeId);
50
+ it("is every delivery that carried the key, in arrival order", async () => {
51
+ const journal = await mixed();
52
+ expect(await names(journal, ONE)).toEqual(["n_a", "n_d"]);
53
+ });
54
+ /** The narrowing is the whole correlation: another page view is another read. */
55
+ it("is no delivery of another page view", async () => {
56
+ const journal = await mixed();
57
+ expect(await names(journal, TWO)).toEqual(["n_b"]);
58
+ });
59
+ /**
60
+ * **The one `undefined === undefined` would get wrong.** A delivery that
61
+ * names no page view — a batch from a sender that mints no keys, or one
62
+ * replayed from a fixture — belongs to no page view and must not be
63
+ * gathered into somebody else's.
64
+ */
65
+ it("is no delivery that named no page view", async () => {
66
+ const journal = await mixed();
67
+ expect(await names(journal, ONE)).not.toContain("n_c");
68
+ expect(await names(journal, TWO)).not.toContain("n_c");
69
+ });
70
+ /** Nothing is withheld when no key is named, which is the read every other caller makes. */
71
+ it("is every delivery where no key is named", async () => {
72
+ const journal = await mixed();
73
+ expect(await names(journal)).toEqual(["n_a", "n_b", "n_c", "n_d"]);
74
+ });
75
+ /**
76
+ * A key nothing carries is an empty page rather than a refusal — which is
77
+ * what a page view whose deliveries the sweep has taken looks like, and the
78
+ * state a drawer opened on a link from last month is in.
79
+ */
80
+ it("is an empty page for a key nothing carries", async () => {
81
+ const journal = await mixed();
82
+ expect(await names(journal, viewKey(9))).toEqual([]);
83
+ });
84
+ /** The limit still clamps and the ends still answer, because this is a page like any other. */
85
+ it("is paged like every other read", async () => {
86
+ const journal = await mixed();
87
+ const page = unwrap(await journal.read({ view: ONE, limit: 1 }));
88
+ expect(page.batches.map((batch) => batch.signals[0]?.nodeId)).toEqual(["n_a"]);
89
+ expect(page.newer).not.toBeNull();
90
+ expect(page.older).toBeNull();
91
+ });
92
+ });
93
+ };
94
+ //# sourceMappingURL=correlated.contract.js.map
@@ -1,4 +1,7 @@
1
1
  import type { AudienceId } from "../audience/audience.js";
2
+ import type { ActedHourCount } from "./acted.js";
3
+ import type { FunnelHourCount } from "./funnel-hours.js";
4
+ import type { ArrivalHourCount } from "./arrivals.js";
2
5
  import type { ReaderRegionCount } from "./region.js";
3
6
  import type { FunnelAnswer, ReaderTally } from "./rollup.js";
4
7
  import type { RevisionViews } from "./page-views.js";
@@ -6,6 +9,35 @@ export declare const pageViewKey: (count: RevisionViews) => string;
6
9
  export declare const tallyKey: (tally: ReaderTally) => string;
7
10
  export declare const funnelKey: (answer: FunnelAnswer) => string;
8
11
  export declare const regionKey: (count: ReaderRegionCount) => string;
12
+ /**
13
+ * A revision and an hour.
14
+ *
15
+ * The fourth counter the door writes and the second it composes by hand: one
16
+ * delivery's openings all carry the same hour, so two of these can only collide
17
+ * where a delivery opened page views of one revision twice over — which
18
+ * `openingsOf` has already folded. The key is here anyway, with the other
19
+ * three, because *today's callers cannot emit a duplicate* is a property of
20
+ * today's callers (see the note above).
21
+ */
22
+ export declare const arrivalKey: (count: ArrivalHourCount) => string;
23
+ /**
24
+ * A revision, a part and an hour, which is the fifth counter and the second
25
+ * with a clock in its key (`acted.ts`).
26
+ *
27
+ * The hour is last for the reason it is last in the table's primary key: a
28
+ * reading of one part over a range is a prefix of this, and a reading of one
29
+ * hour across a page is the index beside it.
30
+ */
31
+ export declare const actedKey: (count: ActedHourCount) => string;
32
+ /**
33
+ * A revision, a pair's two ends and an hour, which is the sixth counter and the
34
+ * third with a clock in its key (`funnel-hours.ts`).
35
+ *
36
+ * The ends are spelled by `endOf` above, so the hourly row and the total row
37
+ * agree about what makes two funnels the same question — the identity 0158
38
+ * makes permanent if the two places disagree about it.
39
+ */
40
+ export declare const funnelHourKey: (count: FunnelHourCount) => string;
9
41
  /**
10
42
  * The same counter, in one audience (0284).
11
43
  *
@@ -42,5 +74,24 @@ export declare const addPageViewCounts: (standing: RevisionViews, next: Revision
42
74
  */
43
75
  export declare const addTallies: (standing: ReaderTally, next: ReaderTally) => ReaderTally;
44
76
  export declare const addFunnelAnswers: (standing: FunnelAnswer, next: FunnelAnswer) => FunnelAnswer;
77
+ /** Page views that began in one hour, added. */
78
+ export declare const addArrivalCounts: (standing: ArrivalHourCount, next: ArrivalHourCount) => ArrivalHourCount;
79
+ /**
80
+ * What readers did to one part in one hour, added.
81
+ *
82
+ * `type` is the one column that is not a number and the later row wins it,
83
+ * which is what `SET type = excluded.type` does — so the fold in front of the
84
+ * driver does not become a third answer.
85
+ */
86
+ export declare const addActedCounts: (standing: ActedHourCount, next: ActedHourCount) => ActedHourCount;
87
+ /**
88
+ * One pair's hour, added.
89
+ *
90
+ * Both numbers are distinct counts of page views, which they may be here for
91
+ * the one reason `funnel-hours.ts` gives at length: a view is filed under a
92
+ * single hour, so two rows naming one pair-hour are two folds' worth of
93
+ * disjoint cohorts and adding them is exact rather than generous.
94
+ */
95
+ export declare const addFunnelHourCounts: (standing: FunnelHourCount, next: FunnelHourCount) => FunnelHourCount;
45
96
  export declare const addRegionCounts: (standing: ReaderRegionCount, next: ReaderRegionCount) => ReaderRegionCount;
46
97
  //# sourceMappingURL=counters.d.ts.map
@@ -37,6 +37,35 @@ export const tallyKey = (tally) => `${revisionKey(tally)} ${tally.nodeId}`;
37
37
  const endOf = (end) => `${end.nodeId}:${end.kind}`;
38
38
  export const funnelKey = (answer) => `${revisionKey(answer)} ${endOf(answer.pair.from)} ${endOf(answer.pair.to)}`;
39
39
  export const regionKey = (count) => `${revisionKey(count)} ${count.region}`;
40
+ /**
41
+ * A revision and an hour.
42
+ *
43
+ * The fourth counter the door writes and the second it composes by hand: one
44
+ * delivery's openings all carry the same hour, so two of these can only collide
45
+ * where a delivery opened page views of one revision twice over — which
46
+ * `openingsOf` has already folded. The key is here anyway, with the other
47
+ * three, because *today's callers cannot emit a duplicate* is a property of
48
+ * today's callers (see the note above).
49
+ */
50
+ export const arrivalKey = (count) => `${revisionKey(count)} ${count.hour}`;
51
+ /**
52
+ * A revision, a part and an hour, which is the fifth counter and the second
53
+ * with a clock in its key (`acted.ts`).
54
+ *
55
+ * The hour is last for the reason it is last in the table's primary key: a
56
+ * reading of one part over a range is a prefix of this, and a reading of one
57
+ * hour across a page is the index beside it.
58
+ */
59
+ export const actedKey = (count) => `${revisionKey(count)} ${count.nodeId} ${count.hour}`;
60
+ /**
61
+ * A revision, a pair's two ends and an hour, which is the sixth counter and the
62
+ * third with a clock in its key (`funnel-hours.ts`).
63
+ *
64
+ * The ends are spelled by `endOf` above, so the hourly row and the total row
65
+ * agree about what makes two funnels the same question — the identity 0158
66
+ * makes permanent if the two places disagree about it.
67
+ */
68
+ export const funnelHourKey = (count) => `${revisionKey(count)} ${endOf(count.pair.from)} ${endOf(count.pair.to)} ${count.hour}`;
40
69
  /**
41
70
  * The same counter, in one audience (0284).
42
71
  *
@@ -98,5 +127,34 @@ export const addFunnelAnswers = (standing, next) => ({
98
127
  reached: standing.reached + next.reached,
99
128
  converted: standing.converted + next.converted,
100
129
  });
130
+ /** Page views that began in one hour, added. */
131
+ export const addArrivalCounts = (standing, next) => ({ ...next, views: standing.views + next.views });
132
+ /**
133
+ * What readers did to one part in one hour, added.
134
+ *
135
+ * `type` is the one column that is not a number and the later row wins it,
136
+ * which is what `SET type = excluded.type` does — so the fold in front of the
137
+ * driver does not become a third answer.
138
+ */
139
+ export const addActedCounts = (standing, next) => ({
140
+ ...next,
141
+ activations: standing.activations + next.activations,
142
+ opens: standing.opens + next.opens,
143
+ closes: standing.closes + next.closes,
144
+ completions: standing.completions + next.completions,
145
+ });
146
+ /**
147
+ * One pair's hour, added.
148
+ *
149
+ * Both numbers are distinct counts of page views, which they may be here for
150
+ * the one reason `funnel-hours.ts` gives at length: a view is filed under a
151
+ * single hour, so two rows naming one pair-hour are two folds' worth of
152
+ * disjoint cohorts and adding them is exact rather than generous.
153
+ */
154
+ export const addFunnelHourCounts = (standing, next) => ({
155
+ ...next,
156
+ reached: standing.reached + next.reached,
157
+ converted: standing.converted + next.converted,
158
+ });
101
159
  export const addRegionCounts = (standing, next) => ({ ...next, views: standing.views + next.views });
102
160
  //# sourceMappingURL=counters.js.map
@@ -39,10 +39,12 @@ import { type StoredPageViews } from "./page-views.js";
39
39
  * rows — and then it is multiplied by a count that does, so the straddle walks
40
40
  * straight back into the ranking key at the last step.
41
41
  *
42
- * So the key here is that figure put **on the scale the door counts in**:
43
- * `readers ÷ (1 + inflation)`, where the inflation is the later window's own
44
- * `drift ÷ opened` off that revision's own door row, picked out with the rule
45
- * published beside the counter rather than written again
42
+ * So the key here is that figure put **on the scale the door counts in**, by
43
+ * `atDoorScale` off that revision's own door row
44
+ * ([0265](../../decisions/0265-what-readers-do-inside-a-kind-of-part-is-a-share-of-the-readers-who-met-it-and-the-door-is-only-a-weight.md),
45
+ * [0346](../../decisions/0346-the-doors-scale-is-total-so-the-three-ranking-keys-read-the-one-rule.md)).
46
+ * The row is the later window's and is picked out with the rule published beside
47
+ * the counter rather than written again
46
48
  * ([0219](../../decisions/0219-a-page-view-is-counted-once-at-the-door-and-the-over-count-in-the-node-counters-is-a-measurement.md)).
47
49
  * What comes out is not a count of people and is deliberately not rounded into
48
50
  * one.
@@ -163,6 +165,28 @@ export type DeploymentChangeSilence =
163
165
  */
164
166
  | "unsplit";
165
167
  export declare const DEPLOYMENT_CHANGE_SILENCES: readonly DeploymentChangeSilence[];
168
+ /**
169
+ * One line per silence, for a surface saying why a page is in neither order.
170
+ *
171
+ * **The sentences are the orders' own, moved here rather than written again.**
172
+ * Every member is also a {@link MovementStanding} and
173
+ * {@link describeMovementStanding} has had a line for each since the orders
174
+ * were built; it defers to this for the six they share, and the text is
175
+ * unchanged from what it returned.
176
+ *
177
+ * Each one names **which of the two windows** it is about, because every member
178
+ * here is a statement about a side rather than about the comparison: a sentence
179
+ * that said *no view of its revision* without saying which window would send a
180
+ * deployment to look at the wrong week.
181
+ *
182
+ * **One sentence of the six is not the standing's own text and says so here.**
183
+ * `inconsistent` read *it reports more readers at a stop than have ever
184
+ * appeared*, which is the only member whose wording left the window out while
185
+ * its own doc comment above says *in the later window*. Two words are added and
186
+ * nothing else of it moves; the standing prints the corrected line because it
187
+ * defers to this.
188
+ */
189
+ export declare const describeDeploymentChangeSilence: (silence: DeploymentChangeSilence) => string;
166
190
  /** Where one page stands in the two orders, or why it is in neither. */
167
191
  export type MovementStanding =
168
192
  /** In at least one of the orders, with a movement and a scale for it. */
@@ -1,5 +1,6 @@
1
1
  import { everyMemberOf } from "../closed-set.js";
2
2
  import { formKeyOf, readingKeyOf } from "./audiences.js";
3
+ import { atDoorScale, doorOf } from "./door.js";
3
4
  import { pageViewsFor } from "./page-views.js";
4
5
  export const DEPLOYMENT_CHANGE_SILENCES = everyMemberOf()([
5
6
  "unread",
@@ -9,6 +10,43 @@ export const DEPLOYMENT_CHANGE_SILENCES = everyMemberOf()([
9
10
  "unopened",
10
11
  "inconsistent",
11
12
  ]);
13
+ /**
14
+ * One line per silence, for a surface saying why a page is in neither order.
15
+ *
16
+ * **The sentences are the orders' own, moved here rather than written again.**
17
+ * Every member is also a {@link MovementStanding} and
18
+ * {@link describeMovementStanding} has had a line for each since the orders
19
+ * were built; it defers to this for the six they share, and the text is
20
+ * unchanged from what it returned.
21
+ *
22
+ * Each one names **which of the two windows** it is about, because every member
23
+ * here is a statement about a side rather than about the comparison: a sentence
24
+ * that said *no view of its revision* without saying which window would send a
25
+ * deployment to look at the wrong week.
26
+ *
27
+ * **One sentence of the six is not the standing's own text and says so here.**
28
+ * `inconsistent` read *it reports more readers at a stop than have ever
29
+ * appeared*, which is the only member whose wording left the window out while
30
+ * its own doc comment above says *in the later window*. Two words are added and
31
+ * nothing else of it moves; the standing prints the corrected line because it
32
+ * defers to this.
33
+ */
34
+ export const describeDeploymentChangeSilence = (silence) => {
35
+ switch (silence) {
36
+ case "unread":
37
+ return "one of the two windows reported no view of its revision";
38
+ case "mispaired":
39
+ return "the two readings are of different pages, so there is no movement here";
40
+ case "unsplit":
41
+ return "one window holds two forms of the page and says which readers neither";
42
+ case "unscaled":
43
+ return "no page views counted at the later door, so its movement is not comparable with another page's";
44
+ case "unopened":
45
+ return "the later page-view row is there and nothing has said a page view began";
46
+ case "inconsistent":
47
+ return "it reports more readers at a stop in the later window than have ever appeared";
48
+ }
49
+ };
12
50
  export const MOVEMENT_STANDINGS = everyMemberOf()([
13
51
  "ranked",
14
52
  "unmoved",
@@ -26,18 +64,8 @@ export const describeMovementStanding = (standing) => {
26
64
  return "in an order, by the readers its sharpest movement moves at the door's scale";
27
65
  case "unmoved":
28
66
  return "compared, and nothing on it moved by as much as one reader";
29
- case "unread":
30
- return "one of the two windows reported no view of its revision";
31
- case "mispaired":
32
- return "the two readings are of different pages, so there is no movement here";
33
- case "unsplit":
34
- return "one window holds two forms of the page and says which readers neither";
35
- case "unscaled":
36
- return "no page views counted at the later door, so its movement is not comparable with another page's";
37
- case "unopened":
38
- return "the later page-view row is there and nothing has said a page view began";
39
- case "inconsistent":
40
- return "it reports more readers at a stop than have ever appeared";
67
+ default:
68
+ return describeDeploymentChangeSilence(standing);
41
69
  }
42
70
  };
43
71
  const EMPTY_STANDINGS = Object.freeze(Object.fromEntries(MOVEMENT_STANDINGS.map((standing) => [standing, 0])));
@@ -70,13 +98,25 @@ const pairKeyOf = (change) => `${formKeyOfChange(change)}\u0000${change.revision
70
98
  * The magnitude is taken of the comparison's own ranking figure rather than
71
99
  * multiplied up again here, because deriving it twice is how two screens come to
72
100
  * disagree about which band a change hurt.
101
+ *
102
+ * **A `null` door is *do not scale this one*** and not *this page has no door*:
103
+ * the caller hands one in for a ranked row and withholds it for a row whose
104
+ * counters disagree with the door row, which publishes the movement's share
105
+ * without a headcount against it.
106
+ *
107
+ * The scale itself is the rule published beside the counter (0346). It was
108
+ * `Math.abs(at.readersKept) ÷ (1 + inflation)` here, which is the same rule by a
109
+ * different route — and this figure is a share movement times a count, so it is
110
+ * **not a whole number**: on a page with no drift the two routes differ in the
111
+ * last place, and the published rule is the one that leaves a figure the door has
112
+ * nothing to correct exactly as it found it.
73
113
  */
74
- const movementOf = (at, inflation) => at === null
114
+ const movementOf = (at, scale) => at === null
75
115
  ? null
76
116
  : {
77
117
  at,
78
118
  share: Math.abs(at.improvement),
79
- readers: inflation === null ? null : Math.abs(at.readersKept) / (1 + inflation),
119
+ readers: scale === null ? null : atDoorScale(Math.abs(at.readersKept), scale),
80
120
  };
81
121
  /**
82
122
  * The standing a comparison's own silence puts a page in.
@@ -150,11 +190,12 @@ const rowOf = (change, door) => {
150
190
  improved: movementOf(change.mostKept, null),
151
191
  };
152
192
  }
193
+ const scale = doorOf(door);
153
194
  return {
154
195
  ...where,
155
196
  standing: "ranked",
156
- worsened: movementOf(change.mostLost, door.inflation),
157
- improved: movementOf(change.mostKept, door.inflation),
197
+ worsened: movementOf(change.mostLost, scale),
198
+ improved: movementOf(change.mostKept, scale),
158
199
  };
159
200
  };
160
201
  /** Tree id, then newest later revision first, which is the order a page's rows are read in. */