@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,236 @@
1
+ /**
2
+ * The seventh contract suite both reader-signal tally stores are run against:
3
+ * **what readers did to a part, filed under the hour they did it in, and the
4
+ * hours of a part summing to the part's own counters** (`acted.ts`).
5
+ *
6
+ * Here rather than beside the three in `src/testing/reader-signal-contract.ts`
7
+ * for the reason `arrivals.contract.ts` is: that directory is another lane's
8
+ * and this is reader-signal work.
9
+ *
10
+ * **Every property here needs two implementations to be worth asserting**, and
11
+ * they are the same three hazards the arrivals suite names, one table deeper.
12
+ * The hour is a `timestamptz` in one store and a number in the other; a part's
13
+ * row is written in the same transaction as the tally it slices in one and
14
+ * through two maps in the other; and two rows naming one part-hour inside a
15
+ * single call are an `ON CONFLICT` Postgres **raises** on and a `Map` silently
16
+ * overwrites. Each is a way for a goal's chart to stop summing to the goal's
17
+ * own figure, which is permanent (0158).
18
+ */
19
+ import { describe, expect, it } from "vitest";
20
+ import { nodeId, OTHER_TREE, primitiveType, RIDERS, SKIERS, TREE } from "../testing/reader-signal-contract.js";
21
+ import { ARRIVAL_HOUR_MS } from "./arrivals.js";
22
+ const HOUR = ARRIVAL_HOUR_MS;
23
+ const MIDNIGHT = Date.parse("2026-11-06T00:00:00.000Z");
24
+ const at = (hour, minutes = 0) => new Date(MIDNIGHT + hour * HOUR + minutes * 60_000).toISOString();
25
+ const hourOf = (hour) => MIDNIGHT + hour * HOUR;
26
+ const pressed = (hour, overrides = {}) => ({
27
+ treeId: TREE,
28
+ revision: 1,
29
+ nodeId: nodeId("buy"),
30
+ type: primitiveType("loom.button"),
31
+ hour: hourOf(hour),
32
+ activations: 1,
33
+ opens: 0,
34
+ closes: 0,
35
+ completions: 0,
36
+ ...overrides,
37
+ });
38
+ const unwrap = (result) => {
39
+ if (!result.ok)
40
+ throw new Error(result.error.detail);
41
+ return result.value;
42
+ };
43
+ export const describeActedHourContract = (name, make) => {
44
+ describe(`${name} — what readers did, by the hour they did it in`, () => {
45
+ const counted = async () => {
46
+ const store = await make();
47
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9, { activations: 2 })] }, at(9, 30), SKIERS));
48
+ return store;
49
+ };
50
+ it("files what readers did under the hour it was folded with", async () => {
51
+ const store = await counted();
52
+ const { hours } = unwrap(await store.acted());
53
+ expect(hours).toEqual([
54
+ {
55
+ audienceId: SKIERS,
56
+ treeId: TREE,
57
+ revision: 1,
58
+ nodeId: nodeId("buy"),
59
+ type: primitiveType("loom.button"),
60
+ hour: hourOf(9),
61
+ activations: 2,
62
+ opens: 0,
63
+ closes: 0,
64
+ completions: 0,
65
+ updatedAt: at(9, 30),
66
+ },
67
+ ]);
68
+ });
69
+ it("adds a second window's rows to the same part-hour", async () => {
70
+ const store = await counted();
71
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9)] }, at(9, 55), SKIERS));
72
+ const { hours } = unwrap(await store.acted());
73
+ expect(hours).toHaveLength(1);
74
+ expect(hours[0]?.activations).toBe(3);
75
+ });
76
+ it("keeps the next hour's presses in their own row", async () => {
77
+ const store = await counted();
78
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(10)] }, at(10), SKIERS));
79
+ const { hours } = unwrap(await store.acted());
80
+ expect(hours.map((row) => [row.hour, row.activations])).toEqual(expect.arrayContaining([
81
+ [hourOf(9), 2],
82
+ [hourOf(10), 1],
83
+ ]));
84
+ });
85
+ /**
86
+ * Two rows naming one part-hour inside a single call are added, which is
87
+ * the guarantee `counters.ts` gives in front of the driver: Postgres
88
+ * refuses to affect one row twice in one command and a `Map` would keep
89
+ * the last.
90
+ */
91
+ it("adds two rows of one part-hour handed over together", async () => {
92
+ const store = await make();
93
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9), pressed(9, { activations: 4 })] }, at(9), SKIERS));
94
+ const { hours } = unwrap(await store.acted());
95
+ expect(hours).toHaveLength(1);
96
+ expect(hours[0]?.activations).toBe(5);
97
+ });
98
+ it("counts the four kinds of doing apart", async () => {
99
+ const store = await make();
100
+ unwrap(await store.apply({
101
+ tallies: [],
102
+ funnels: [],
103
+ acted: [pressed(9, { activations: 0, opens: 3, closes: 2, completions: 1 })],
104
+ }, at(9), SKIERS));
105
+ expect(unwrap(await store.acted()).hours[0]).toMatchObject({
106
+ activations: 0,
107
+ opens: 3,
108
+ closes: 2,
109
+ completions: 1,
110
+ });
111
+ });
112
+ it("takes the later window's word for what a part is", async () => {
113
+ const store = await counted();
114
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9, { type: primitiveType("loom.link") })] }, at(9, 40), SKIERS));
115
+ expect(unwrap(await store.acted()).hours[0]?.type).toBe(primitiveType("loom.link"));
116
+ });
117
+ it("keeps two parts of one hour apart, and sums them when neither is named", async () => {
118
+ const store = await counted();
119
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9, { nodeId: nodeId("signup") })] }, at(9, 45), SKIERS));
120
+ expect(unwrap(await store.acted()).hours).toHaveLength(2);
121
+ expect(unwrap(await store.acted({ nodeId: nodeId("buy") })).hours).toHaveLength(1);
122
+ expect(unwrap(await store.acted({ nodeId: nodeId("buy") })).hours[0]?.activations).toBe(2);
123
+ });
124
+ it("keeps an hour of two audiences apart (0284)", async () => {
125
+ const store = await counted();
126
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9)] }, at(9), RIDERS));
127
+ expect(unwrap(await store.acted()).hours).toHaveLength(2);
128
+ expect(unwrap(await store.acted({ audience: RIDERS })).hours[0]?.activations).toBe(1);
129
+ });
130
+ it("keeps an hour of two trees apart", async () => {
131
+ const store = await counted();
132
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9, { treeId: OTHER_TREE })] }, at(9), SKIERS));
133
+ expect(unwrap(await store.acted()).hours).toHaveLength(2);
134
+ expect(unwrap(await store.acted({ treeId: TREE })).hours).toHaveLength(1);
135
+ });
136
+ it("keeps an hour of two revisions apart, so a change can be read across one", async () => {
137
+ const store = await counted();
138
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9, { revision: 2 })] }, at(9), SKIERS));
139
+ expect(unwrap(await store.acted()).hours).toHaveLength(2);
140
+ expect(unwrap(await store.acted({ revision: 2 })).hours[0]?.activations).toBe(1);
141
+ });
142
+ it("writes nothing for a window in which readers did nothing", async () => {
143
+ const store = await make();
144
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [] }, at(9), SKIERS));
145
+ expect(unwrap(await store.acted()).hours).toEqual([]);
146
+ expect(unwrap(await store.acted()).begins).toBeUndefined();
147
+ });
148
+ describe("over a range", () => {
149
+ const spread = async () => {
150
+ const store = await make();
151
+ for (const hour of [1, 5, 9]) {
152
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(hour, { activations: hour })] }, at(hour), SKIERS));
153
+ }
154
+ return store;
155
+ };
156
+ it("holds the hours from the start of the range to the end, and not the ends' neighbours", async () => {
157
+ const store = await spread();
158
+ const { hours } = unwrap(await store.acted({ from: hourOf(5), to: hourOf(9) }));
159
+ expect(hours.map((row) => row.activations)).toEqual([5]);
160
+ });
161
+ it("is unbounded on a side the request leaves out", async () => {
162
+ const store = await spread();
163
+ expect(unwrap(await store.acted({ to: hourOf(9) })).hours).toHaveLength(2);
164
+ expect(unwrap(await store.acted({ from: hourOf(5) })).hours).toHaveLength(2);
165
+ });
166
+ it("answers an empty range with no hours and the beginning still named", async () => {
167
+ const store = await spread();
168
+ const read = unwrap(await store.acted({ from: hourOf(20), to: hourOf(21) }));
169
+ expect(read.hours).toEqual([]);
170
+ expect(read.begins).toBe(hourOf(1));
171
+ });
172
+ });
173
+ describe("the hour counting began", () => {
174
+ it("is the earliest hour the scope has, whatever range was asked for", async () => {
175
+ const store = await make();
176
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9)] }, at(9), SKIERS));
177
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(2)] }, at(2), SKIERS));
178
+ expect(unwrap(await store.acted({ from: hourOf(9), to: hourOf(10) })).begins).toBe(hourOf(2));
179
+ });
180
+ /**
181
+ * The clause a goal depends on: a goal made this afternoon on a part
182
+ * nobody pressed until this afternoon has been measurable since this
183
+ * afternoon, and a beginning taken over the deployment would draw a year
184
+ * of noughts behind it.
185
+ */
186
+ it("narrows to the part, so a goal says when its own part was first acted in", async () => {
187
+ const store = await make();
188
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(2)] }, at(2), SKIERS));
189
+ unwrap(await store.apply({ tallies: [], funnels: [], acted: [pressed(9, { nodeId: nodeId("signup") })] }, at(9), SKIERS));
190
+ expect(unwrap(await store.acted({ nodeId: nodeId("signup") })).begins).toBe(hourOf(9));
191
+ });
192
+ it("is absent where nothing has ever been counted", async () => {
193
+ const store = await make();
194
+ expect(unwrap(await store.acted()).begins).toBeUndefined();
195
+ });
196
+ });
197
+ /**
198
+ * The invariant the whole design rests on: the hourly rows are a slice of
199
+ * the tallies, so a window's hours add up to the same occurrences its
200
+ * tallies carry. Both are written here by one call, which is what the fold
201
+ * does.
202
+ */
203
+ it("holds the same occurrences as the tally it slices", async () => {
204
+ const store = await make();
205
+ unwrap(await store.apply({
206
+ tallies: [
207
+ {
208
+ treeId: TREE,
209
+ revision: 1,
210
+ nodeId: nodeId("buy"),
211
+ type: primitiveType("loom.button"),
212
+ views: 4,
213
+ reached: 4,
214
+ engaged: 0,
215
+ dwellMs: 9_000,
216
+ activations: 5,
217
+ opens: 0,
218
+ closes: 0,
219
+ completions: 0,
220
+ },
221
+ ],
222
+ funnels: [],
223
+ acted: [pressed(9, { activations: 2 }), pressed(10, { activations: 3 })],
224
+ }, at(10), SKIERS));
225
+ const { hours } = unwrap(await store.acted());
226
+ const [tally] = unwrap(await store.tallies());
227
+ expect(hours.reduce((sum, row) => sum + row.activations, 0)).toBe(tally?.activations);
228
+ });
229
+ it("is not changed by being read", async () => {
230
+ const store = await counted();
231
+ expect(unwrap(await store.acted()).hours[0]?.activations).toBe(2);
232
+ expect(unwrap(await store.acted()).hours[0]?.activations).toBe(2);
233
+ });
234
+ });
235
+ };
236
+ //# sourceMappingURL=acted.contract.js.map
@@ -0,0 +1,359 @@
1
+ import type { NodeId, TreeId } from "../ids.js";
2
+ import type { PrimitiveType } from "../primitive-type.js";
3
+ import type { AudienceId } from "../audience/audience.js";
4
+ import { type ArrivalCounterHandle, type ArrivalRange, type ArrivalReading, type ArrivalSeriesOptions } from "./arrivals.js";
5
+ import type { ReaderSignalStoreError } from "./journal.js";
6
+ import { type Ratio } from "./ratios.js";
7
+ import type { Result } from "../result.js";
8
+ import { DELEGATED_READER_SIGNAL_KINDS } from "./kinds.js";
9
+ /**
10
+ * **What readers did, by the hour they did it in.**
11
+ *
12
+ * [`arrivals.ts`](arrivals.ts) put a clock on one counter: page views, by the
13
+ * hour they began in (0356). It let the portal draw a range picker, a figure
14
+ * for the range and a chart of twenty-four bars — and it left every other
15
+ * question on that screen unanswerable over a range, because a tally keeps no
16
+ * time (rule 5 of `docs/signals.md`) and the hourly counter counted arrivals
17
+ * only. `Loom portal` filed for the rest of it the same morning: *a goal's
18
+ * figure for a range, and `By page`'s bars for one, need what readers did on a
19
+ * part counted by hour, and only page views are.*
20
+ *
21
+ * A goal is one kind of thing a reader does to one part
22
+ * ([0350](../../decisions/0350-a-project-sets-goals-from-signals-already-collected-and-one-of-them-is-primary.md)):
23
+ * *presses* of a button, *sends* of a form, *opens* of a disclosure. Those are
24
+ * three of the five kinds and they are exactly
25
+ * `DELEGATED_READER_SIGNAL_KINDS` — the kinds a reader *aimed at something* to
26
+ * cause (0167). So this is the seventh counter, filed per part per hour, and it
27
+ * holds those three kinds and nothing else.
28
+ *
29
+ * ## Why not every counter a tally has
30
+ *
31
+ * The obvious table is *the tallies, with an hour in the key*, and it is the
32
+ * wrong one twice over.
33
+ *
34
+ * - **`views`, `reached` and `engaged` are distinct counts of page views, and
35
+ * distinctness does not add.** A reader whose page view crosses midnight is
36
+ * one view in each hour and two in their sum, so an hourly table of them
37
+ * would publish a denominator that grows with how finely it is sliced — and
38
+ * the straddle a rollup window already causes (0147) at least has a
39
+ * measurement bounding it. **The denominator an hourly rate needs is already
40
+ * exact and already hourly**: page views that began in an hour, counted once,
41
+ * at the door (0214, 0356). Dividing this counter by that one is the rate
42
+ * 0350 clause 4 defines, taken over a range.
43
+ * - **`dwellMs` is a byproduct of a page being on screen rather than a thing a
44
+ * reader did**, and it is the one counter whose rows are as numerous as the
45
+ * page is large: a `dwelled` signal is observed for every addressed node that
46
+ * comes into view, so an hourly dwell row per part on a 6,000-node page is
47
+ * 6,000 rows an hour — 144,000 a day, for ever, per revision — against a
48
+ * durable table that is never swept. The three kinds here are **bounded by
49
+ * what readers did**: a reader who presses one button on that same page
50
+ * writes one row.
51
+ *
52
+ * That boundary is the whole design, and it is a sentence a deployment can
53
+ * read: **this counter grows with what readers do, not with how big a page
54
+ * is.**
55
+ *
56
+ * ## Written by the fold, from the same pass
57
+ *
58
+ * The door writes the arrivals, because nothing but the door knows which page
59
+ * views were already underway (0214). These are written by the fold, in the
60
+ * same `applyWindow` transaction as the tallies they slice, from **the same
61
+ * pass of `rollUp`** — not a second walk over the window.
62
+ *
63
+ * That is not a tidiness: `rollUp` refuses a batch it has already folded in
64
+ * this window (0314), and the refusal is a judgement made once per batch. A
65
+ * second pass would make it twice, against a different grouping, and a repeat
66
+ * that fell in two different hours would be refused by one pass and counted by
67
+ * the other — so the hours would stop summing to the tally they are a slice
68
+ * of, permanently and invisibly (0158). One pass makes the sum an invariant
69
+ * instead, and `rollup.test.ts` asserts it.
70
+ *
71
+ * **The hour is the door's instant, never the sender's.** `receivedAt` is a
72
+ * server clock; `sentAt` is a number a page said, and a chart drawn from it
73
+ * would be a chart a page could move bars on (0355).
74
+ *
75
+ * ## What an hour's count settles
76
+ *
77
+ * An hour's rows stop moving once every delivery received in that hour has been
78
+ * folded — which is the first fold whose horizon is past the end of the hour,
79
+ * so one collection window after it. A reading of the hour before that is
80
+ * reading an hour still being filled, exactly as the last bar of *the last 24
81
+ * hours* is, and {@link ActedHour.whole} is how a surface says so.
82
+ *
83
+ * Pure: no store, no clock, no DOM, and no import that reaches a package.
84
+ */
85
+ /**
86
+ * The three kinds this counter holds, which are the kinds a reader aimed at
87
+ * something to cause (0167) and the kinds a goal may be made of (0350).
88
+ *
89
+ * Not a new vocabulary — a narrowing of the closed five (rule 6), spelled as
90
+ * the list `kinds.ts` already publishes, so a sixth delegated kind would land
91
+ * here by being added there.
92
+ */
93
+ export type ActedKind = (typeof DELEGATED_READER_SIGNAL_KINDS)[number];
94
+ export declare const ACTED_KINDS: readonly ActedKind[];
95
+ /** Whether a signal kind is one this counter holds. */
96
+ export declare const isActedKind: (kind: string) => kind is ActedKind;
97
+ /**
98
+ * What readers did, as four numbers, with nothing saying what they did it to.
99
+ *
100
+ * The four counters are the tally's four occurrence counters that come from the
101
+ * three delegated kinds. `opens` and `closes` are both `disclosed` and are kept
102
+ * apart for the reason the tally keeps them apart: a goal counts openings
103
+ * (0350), and a surface drawing *what readers did* may want to say that a
104
+ * disclosure was opened nine times and shut eight.
105
+ *
106
+ * **All four are occurrences, which is the property every sum over them
107
+ * rests on.** A reader who presses twice is two; two readers who press once
108
+ * each are two; and neither figure is a count of readers, so rows may be added
109
+ * across hours, parts, revisions and audiences without the distinctness trap
110
+ * the tally's `views`, `reached` and `engaged` carry (0147, 0284). Separated
111
+ * from the key for exactly that reason: a subtree's total
112
+ * ([`inside.ts`](inside.ts)) is these four numbers and no key at all.
113
+ */
114
+ export type ActedCounts = {
115
+ readonly activations: number;
116
+ readonly opens: number;
117
+ readonly closes: number;
118
+ readonly completions: number;
119
+ };
120
+ /** What readers did to one part of one revision, in one hour. */
121
+ export type ActedHourCount = ActedCounts & {
122
+ readonly treeId: TreeId;
123
+ readonly revision: number;
124
+ readonly nodeId: NodeId;
125
+ readonly type: PrimitiveType;
126
+ /** The hour it happened in, as the instant that hour began (UTC). */
127
+ readonly hour: number;
128
+ };
129
+ /** An hour's row as the store keeps it. See `StoredTally.audienceId` (0284). */
130
+ export type StoredActedHour = ActedHourCount & {
131
+ readonly audienceId: AudienceId;
132
+ readonly updatedAt: string;
133
+ };
134
+ /**
135
+ * The counter a kind is counted in.
136
+ *
137
+ * `disclosed` is openings, which is the same choice the portal's goal figure
138
+ * makes (0350 clause 4) — published here so the rule is spelled once, in the
139
+ * lane that owns the counters, rather than in each surface that reads them.
140
+ *
141
+ * It takes the counters rather than a row, so the one spelling serves a stored
142
+ * hour and a sum of them alike.
143
+ */
144
+ export declare const actedCountOf: (counts: ActedCounts, kind: ActedKind) => number;
145
+ /**
146
+ * What a ranged read of the counter hands back, which is the shape
147
+ * {@link StoredArrivals} has and for the same two reasons.
148
+ */
149
+ export type StoredActed = {
150
+ /** Every row in the range, in no particular order. */
151
+ readonly hours: readonly StoredActedHour[];
152
+ /**
153
+ * The first hour this scope has ever counted an action in, whatever range was
154
+ * asked for.
155
+ *
156
+ * Absent means *nothing has ever been counted here*, which is a different
157
+ * sentence from *nobody did anything in the range you asked about* (0309,
158
+ * 0347). It narrows with the request, so a goal's figure says when counting
159
+ * began for that part rather than for the deployment.
160
+ */
161
+ readonly begins?: number;
162
+ };
163
+ /** One hour of a range, which is one bar. See {@link ArrivalHour}. */
164
+ export type ActedHour = {
165
+ /** The instant the hour began (UTC). */
166
+ readonly hour: number;
167
+ /** What readers did in it, in the kind this series is of. */
168
+ readonly count: number;
169
+ /**
170
+ * Whether this hour is over and inside the range.
171
+ *
172
+ * False on the hour in progress, and false where the range cuts the hour
173
+ * short — so a surface does not draw the clock as a fall.
174
+ */
175
+ readonly whole: boolean;
176
+ };
177
+ /**
178
+ * What readers did over a range, by hour, in one kind.
179
+ *
180
+ * One kind per series because that is what a goal is, and because a chart with
181
+ * presses and sends added together is a chart of two different things.
182
+ */
183
+ export type ActedSeries = {
184
+ readonly range: ArrivalRange;
185
+ readonly kind: ActedKind;
186
+ /**
187
+ * One entry per hour, ascending, from the later of the range's first hour and
188
+ * the hour counting began. Dense: an hour nobody acted in is `count: 0` and
189
+ * is present.
190
+ */
191
+ readonly hours: readonly ActedHour[];
192
+ /** What readers did inside the range, which is the sum of the hours above. */
193
+ readonly count: number;
194
+ /** The first hour this scope ever counted, carried through from the store. */
195
+ readonly begins?: number;
196
+ /** Whether the range starts before counting did, so the series is shorter than asked for. */
197
+ readonly clipped: boolean;
198
+ };
199
+ /** What a series may be told besides the rows: the kind, and the clock. */
200
+ export type ActedSeriesOptions = ArrivalSeriesOptions & {
201
+ /** Absent reads presses, which is the commonest goal there is (0350). */
202
+ readonly kind?: ActedKind;
203
+ };
204
+ /**
205
+ * The hours of a range, as the counter answers for them.
206
+ *
207
+ * Rows are summed into their hour, so a scope holding several revisions or
208
+ * parts adds — **occurrences add** (unlike the distinct counts this table
209
+ * deliberately does not hold). A caller wanting one part asks the store for
210
+ * one.
211
+ *
212
+ * Rows outside the range are ignored rather than refused, for the reason
213
+ * `arrivalSeriesOf` ignores them: a wider read is what {@link actedChangeOf}
214
+ * narrows twice.
215
+ */
216
+ export declare const actedSeriesOf: (stored: StoredActed, range: ArrivalRange, options?: ActedSeriesOptions) => ActedSeries;
217
+ /**
218
+ * What readers did in a range against what they did in the period before it.
219
+ *
220
+ * The trend the wireframe puts beside a goal, and the figure that is a lie if
221
+ * the earlier period is one the deployment was not counting through.
222
+ */
223
+ export type ActedChange = {
224
+ readonly range: ArrivalRange;
225
+ /** The equal-length period before, which is `arrivalRangeBefore` (0356). */
226
+ readonly before: ArrivalRange;
227
+ readonly kind: ActedKind;
228
+ readonly count: number;
229
+ /**
230
+ * What readers did in the earlier period, or `null` where counting had not
231
+ * begun when it started.
232
+ *
233
+ * `null` is not nought, and the difference is the whole of this field: a
234
+ * deployment that upgraded on Tuesday had no counter before Tuesday and no
235
+ * missing presses either.
236
+ */
237
+ readonly was: number | null;
238
+ /** The quotient, or why there is none (`ratios.ts`). */
239
+ readonly ratio: Ratio;
240
+ };
241
+ /**
242
+ * Both figures and the quotient, from one read spanning both periods.
243
+ *
244
+ * The read has to span both, which is what {@link readReaderActed} is for: the
245
+ * obvious caller reads the range on the screen and reports an earlier period
246
+ * that is empty **because it was not read** (0356).
247
+ */
248
+ export declare const actedChangeOf: (stored: StoredActed, range: ArrivalRange, options?: ActedSeriesOptions) => ActedChange;
249
+ /** What a surface asks for: a range, the narrowing, the kind and the clock. */
250
+ export type ActedReadingRequest = {
251
+ readonly range: ArrivalRange;
252
+ /** The kind the series is of. Absent reads presses. */
253
+ readonly kind?: ActedKind;
254
+ /** Absent reads every tree the handle can see, which is the scope rule (0020). */
255
+ readonly treeId?: TreeId;
256
+ /**
257
+ * The one part this is about, where it is about one.
258
+ *
259
+ * A goal is a kind on a part, so a goal's series passes this and the store
260
+ * answers it from an index rather than by reading the page's other parts.
261
+ * Absent sums every part the narrowing holds, which is *what readers did on
262
+ * this page* rather than *on this part*.
263
+ */
264
+ readonly nodeId?: NodeId;
265
+ /** Absent reads every audience (0284), whose counts then add. */
266
+ readonly audience?: AudienceId | undefined;
267
+ /** Absent reads every revision, whose counts then add — which is what a goal wants (0350). */
268
+ readonly revision?: number;
269
+ /** Now, where the caller has it, so the hour in progress is marked as one. */
270
+ readonly now?: number;
271
+ };
272
+ /** The chart and the figure beside it, from one read. */
273
+ export type ActedReading = {
274
+ readonly series: ActedSeries;
275
+ readonly change: ActedChange;
276
+ };
277
+ /** The one method of the counter handle a reading of this needs. */
278
+ export type ActedCounterHandle = {
279
+ readonly acted: (request?: {
280
+ readonly treeId?: TreeId;
281
+ readonly nodeId?: NodeId;
282
+ readonly audience?: AudienceId | undefined;
283
+ readonly revision?: number;
284
+ readonly from?: number;
285
+ readonly to?: number;
286
+ }) => Promise<Result<StoredActed, ReaderSignalStoreError>>;
287
+ };
288
+ /**
289
+ * The chart, the range's figure and the change on the period before it, in one
290
+ * call against a counter handle.
291
+ *
292
+ * It exists for the reason `readReaderArrivals` does: the composition has a
293
+ * wrong version that type-checks, and it reads as *every press you have is new*
294
+ * on a screen, from a store that holds the right answer. The store handle is
295
+ * narrowed to the one method, so a reading cannot reach a counter it was not
296
+ * asked about.
297
+ */
298
+ export declare const readReaderActed: (store: ActedCounterHandle, request: ActedReadingRequest) => Promise<Result<ActedReading, ReaderSignalStoreError>>;
299
+ /**
300
+ * What readers did in a range, over the page views they did it in.
301
+ *
302
+ * The figure 0350 clause 4 defines — *7 presses in 200 page views, 3.5 per
303
+ * 100* — taken over a range rather than since counting began, which is the
304
+ * figure `docs/portal-wireframes.md` *1 · Signals* puts beside page views in
305
+ * the range.
306
+ *
307
+ * ## The two numbers are counted at different moments, and that is stated
308
+ * rather than hidden
309
+ *
310
+ * The denominator is page views that **began** in the range (0214, 0356). The
311
+ * numerator is what readers **did** in it. So a reader who arrived at 10:59 and
312
+ * pressed at 11:01 is in the eleven o'clock numerator and the ten o'clock
313
+ * denominator, and the two edges of any range are therefore inexact in opposite
314
+ * directions.
315
+ *
316
+ * It is bounded by the edges rather than by the range: over thirty days it is
317
+ * two page views' worth of a month, and over one hour it is the whole of what a
318
+ * figure is about. **So there is no per-hour rate**, only a rate over the
319
+ * range: a series of hourly quotients would publish that boundary error once
320
+ * per bucket, in a shape where *a press with no arrival* reads as an infinite
321
+ * rate rather than as a reader who came in before the hour. The hours are
322
+ * published as counts, which add honestly, and the quotient is taken once.
323
+ */
324
+ export type ActedRate = {
325
+ /**
326
+ * What readers did per hundred page views in the range, or `null` where there
327
+ * is no quotient to take.
328
+ *
329
+ * `null` where the range held no page views at all — including the case worth
330
+ * naming, which is a range holding actions and no arrivals: every reader in
331
+ * it arrived before it began. A nought there would read as *nobody acts*, and
332
+ * the counts beside it say what actually happened.
333
+ */
334
+ readonly per100: number | null;
335
+ /** The same figure for the period before, or `null` on the same terms. */
336
+ readonly was: number | null;
337
+ /** The quotient of the two rates, or why there is none (`ratios.ts`). */
338
+ readonly ratio: Ratio;
339
+ };
340
+ /** What readers did over a range, the page views it happened in, and the rate. */
341
+ export type ActedRateReading = {
342
+ readonly acted: ActedReading;
343
+ readonly arrivals: ArrivalReading;
344
+ readonly rate: ActedRate;
345
+ };
346
+ /** Both figures' handles, which one counter store satisfies. */
347
+ export type ActedRateHandle = ActedCounterHandle & ArrivalCounterHandle;
348
+ /**
349
+ * The figure, the chart, the denominator and the trend, from two reads of one
350
+ * store over one range.
351
+ *
352
+ * **One range, taken once, passed to both halves.** A caller composing this
353
+ * itself has to get the same range into two reads and the same period before it
354
+ * into two comparisons; the failure is a rate whose numerator and denominator
355
+ * describe different stretches of time, which is a number nobody can tell is
356
+ * wrong by looking at it.
357
+ */
358
+ export declare const readReaderActedRate: (store: ActedRateHandle, request: ActedReadingRequest) => Promise<Result<ActedRateReading, ReaderSignalStoreError>>;
359
+ //# sourceMappingURL=acted.d.ts.map