@jam-overture/loom 0.1.0 → 0.2.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 (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -1,17 +1,21 @@
1
1
  import { and, asc, desc, eq, gt, lt, sql } from "drizzle-orm";
2
2
  import { z } from "zod";
3
+ import { DEFAULT_AUDIENCE_ID, audienceIdSchema } from "../audience/audience.js";
3
4
  import { nodeIdSchema, treeIdSchema } from "../ids.js";
4
5
  import { cursorPosition, pageEnds } from "../paging.js";
5
6
  import { primitiveTypeSchema } from "../primitive-type.js";
7
+ import { DEFAULT_APPLICATION_ID, } from "../application/application.js";
6
8
  import { err, ok } from "../result.js";
9
+ import { addFunnelAnswers, addPageViewCounts, addRegionCounts, addTallies, foldedBy, funnelKey, pageViewKey, regionKey, tallyKey, } from "./counters.js";
7
10
  import { clampReaderSignalLimit, } from "./journal.js";
11
+ import { readerRegionSchema, } from "./region.js";
8
12
  import { readerSignalKindSchema, readerSignalSchema, viewKeySchema } from "./signal.js";
9
- import { loomReaderFunnels, loomReaderSignals, loomReaderTallies } from "./schema.js";
13
+ import { loomReaderFunnels, loomReaderPageViews, loomReaderRegions, loomReaderSignals, loomReaderTallies, } from "./schema.js";
10
14
  export * from "./migrate.js";
11
15
  /**
12
16
  * The Drizzle tables are **not** re-exported, unlike the journal's.
13
17
  *
14
- * A deployment needs the two factories below and `ensureReaderSignalsSchema`;
18
+ * A deployment needs the three factories below and `ensureReaderSignalsSchema`;
15
19
  * a `PgTableWithColumns` is how this file talks to the driver. Publishing the
16
20
  * three of them put about 7 KB of generated Drizzle type into the API
17
21
  * reference a reader downloads — for `loomReaderTallies` alone, a signature
@@ -27,6 +31,16 @@ export * from "./migrate.js";
27
31
  * browser composed, and a batch written by an older parser must not reach a
28
32
  * rollup unvalidated.
29
33
  */
34
+ /**
35
+ * Each of the three factories below is a public function that resolves the
36
+ * application and a private one that has it.
37
+ *
38
+ * The split is what keeps `application` a plain `ApplicationId` everywhere it
39
+ * is read rather than an optional unwrapped at each use, so a query cannot
40
+ * filter on `undefined` by forgetting the default. It also leaves the bodies
41
+ * where they were: scoping these tables changed the lines that name a column
42
+ * and nothing else, which is what a reader of the diff should be able to see.
43
+ */
30
44
  const failure = (cause, detail) => ({
31
45
  code: "unavailable",
32
46
  detail: `${detail}: ${cause instanceof Error ? cause.message : String(cause)}`,
@@ -43,6 +57,8 @@ const instantSchema = z
43
57
  .transform((value) => value.toISOString());
44
58
  const receivedSchema = z.object({
45
59
  seq: z.number().int().nonnegative(),
60
+ /** What the batch was filed under, which is always a value — see `ReceivedBatch.audienceId`. */
61
+ audienceId: audienceIdSchema,
46
62
  treeId: treeIdSchema,
47
63
  revision: z.number().int().nonnegative(),
48
64
  sentAt: z.number().int().nonnegative(),
@@ -58,6 +74,7 @@ const receivedSchema = z.object({
58
74
  */
59
75
  const countSchema = z.coerce.number().int().nonnegative();
60
76
  const storedTallySchema = z.object({
77
+ audienceId: audienceIdSchema,
61
78
  treeId: treeIdSchema,
62
79
  revision: z.number().int().nonnegative(),
63
80
  nodeId: nodeIdSchema,
@@ -69,10 +86,12 @@ const storedTallySchema = z.object({
69
86
  activations: countSchema,
70
87
  opens: countSchema,
71
88
  closes: countSchema,
89
+ completions: countSchema,
72
90
  updatedAt: instantSchema,
73
91
  });
74
92
  const storedFunnelSchema = z
75
93
  .object({
94
+ audienceId: audienceIdSchema,
76
95
  treeId: treeIdSchema,
77
96
  revision: z.number().int().nonnegative(),
78
97
  fromNodeId: nodeIdSchema,
@@ -84,6 +103,7 @@ const storedFunnelSchema = z
84
103
  updatedAt: instantSchema,
85
104
  })
86
105
  .transform((row) => ({
106
+ audienceId: row.audienceId,
87
107
  treeId: row.treeId,
88
108
  revision: row.revision,
89
109
  pair: {
@@ -94,12 +114,54 @@ const storedFunnelSchema = z
94
114
  converted: row.converted,
95
115
  updatedAt: row.updatedAt,
96
116
  }));
97
- export const postgresReaderSignalJournal = (db) => ({
117
+ /**
118
+ * `folded_at` is absent rather than `null` on the way out, because *nothing
119
+ * attests a fold* is one state and a reading should not have two spellings of
120
+ * it to check (0274). A row written before the column existed and one no fold
121
+ * has touched are the same answer.
122
+ */
123
+ const storedPageViewsSchema = z
124
+ .object({
125
+ audienceId: audienceIdSchema,
126
+ treeId: treeIdSchema,
127
+ revision: z.number().int().nonnegative(),
128
+ opened: countSchema,
129
+ appearances: countSchema,
130
+ updatedAt: instantSchema,
131
+ foldedAt: instantSchema.nullable().default(null),
132
+ })
133
+ .transform((row) => ({
134
+ audienceId: row.audienceId,
135
+ treeId: row.treeId,
136
+ revision: row.revision,
137
+ opened: row.opened,
138
+ appearances: row.appearances,
139
+ updatedAt: row.updatedAt,
140
+ ...(row.foldedAt === null ? {} : { foldedAt: row.foldedAt }),
141
+ }));
142
+ /**
143
+ * Every read is filtered by the application this handle speaks for (0269), and
144
+ * every write sets it.
145
+ *
146
+ * A reader is filed against the application whose page they read. Folding two
147
+ * would add two customers' counts together, and the addition is not
148
+ * recoverable from the rows afterwards — which is why this landed before
149
+ * anything could construct a second application rather than after.
150
+ */
151
+ export const postgresReaderSignalJournal = (db, scope = {}) => journalIn(db, scope.application ?? DEFAULT_APPLICATION_ID);
152
+ const journalIn = (db, application) => ({
98
153
  receive: async (batches) => {
99
154
  if (batches.length === 0)
100
155
  return ok(undefined);
101
156
  try {
102
157
  await db.insert(loomReaderSignals).values(batches.map((batch) => ({
158
+ applicationId: application,
159
+ /**
160
+ * Resolved here rather than defaulted by the column, so the row a
161
+ * fold reads says what it was filed under whichever sender wrote it
162
+ * (0284).
163
+ */
164
+ audienceId: batch.audience ?? DEFAULT_AUDIENCE_ID,
103
165
  treeId: batch.treeId,
104
166
  revision: batch.revision,
105
167
  sentAt: batch.sentAt,
@@ -121,6 +183,7 @@ export const postgresReaderSignalJournal = (db) => ({
121
183
  const rows = await db
122
184
  .select({
123
185
  seq: loomReaderSignals.seq,
186
+ audienceId: loomReaderSignals.audienceId,
124
187
  treeId: loomReaderSignals.treeId,
125
188
  revision: loomReaderSignals.revision,
126
189
  sentAt: loomReaderSignals.sentAt,
@@ -129,7 +192,7 @@ export const postgresReaderSignalJournal = (db) => ({
129
192
  receivedAt: loomReaderSignals.receivedAt,
130
193
  })
131
194
  .from(loomReaderSignals)
132
- .where(and(request?.treeId === undefined ? undefined : eq(loomReaderSignals.treeId, request.treeId), from === undefined
195
+ .where(and(eq(loomReaderSignals.applicationId, application), request?.treeId === undefined ? undefined : eq(loomReaderSignals.treeId, request.treeId), from === undefined
133
196
  ? undefined
134
197
  : direction === "older"
135
198
  ? lt(loomReaderSignals.seq, from)
@@ -165,7 +228,12 @@ export const postgresReaderSignalJournal = (db) => ({
165
228
  try {
166
229
  const removed = await db
167
230
  .delete(loomReaderSignals)
168
- .where(lt(loomReaderSignals.seq, before))
231
+ /**
232
+ * Scoped like every read, so retention run for one application cannot
233
+ * drop another's buffer. `seq` is database-wide, so an unfiltered
234
+ * `DELETE` here would have taken every application's rows below it.
235
+ */
236
+ .where(and(eq(loomReaderSignals.applicationId, application), lt(loomReaderSignals.seq, before)))
169
237
  .returning({ seq: loomReaderSignals.seq });
170
238
  return ok({ removed: removed.length });
171
239
  }
@@ -174,121 +242,356 @@ export const postgresReaderSignalJournal = (db) => ({
174
242
  }
175
243
  },
176
244
  });
177
- /** Both counter tables are filtered the same way, on the two columns they share. */
178
- const within = (columns, request) => and(request?.treeId === undefined ? undefined : eq(columns.treeId, request.treeId), request?.revision === undefined ? undefined : eq(columns.revision, request.revision));
179
- export const postgresReaderTallyStore = (db) => ({
245
+ /**
246
+ * Every counter table is filtered the same way, on the four columns they all
247
+ * share.
248
+ *
249
+ * The application is first and is not optional, unlike the three a request may
250
+ * narrow by: a reading always happens inside one application, and taking it
251
+ * here rather than at each call site is what stops a counter query being
252
+ * written without it.
253
+ *
254
+ * **The audience is one of the optional three** (0284), which is the difference
255
+ * between the two dimensions in one line: no reading spans two applications,
256
+ * and a reading that compares two audiences is the point of serving two.
257
+ */
258
+ const within = (columns, application, request) => and(eq(columns.applicationId, application), request?.audience === undefined ? undefined : eq(columns.audienceId, request.audience), request?.treeId === undefined ? undefined : eq(columns.treeId, request.treeId), request?.revision === undefined ? undefined : eq(columns.revision, request.revision));
259
+ /** Scoped on the same terms as the journal — see its note. */
260
+ export const postgresReaderTallyStore = (db, scope = {}) => tallyStoreIn(db, scope.application ?? DEFAULT_APPLICATION_ID);
261
+ /**
262
+ * The entries of a window that have anything to write, each with its audience
263
+ * resolved.
264
+ *
265
+ * Two entries naming one audience are left as two: they are two commands in
266
+ * one transaction, and a command's effect is visible to the next one, so they
267
+ * add — which is what `ReaderTallyStore.applyWindow` promises and what the
268
+ * memory store does by writing through a `Map`. Gathering them first would have
269
+ * been fewer statements and **the same answer**, so it would have been a line
270
+ * no test could fail on (0231). The guarantee that matters is per command, and
271
+ * `foldedBy` below is where it is kept: `ON CONFLICT … DO UPDATE` refuses to
272
+ * affect one row twice inside a single command, which is the disagreement
273
+ * `counters.ts` was bitten by.
274
+ */
275
+ const writable = (window) => window
276
+ .filter(({ tallies, funnels, appearances = [] }) => tallies.length > 0 || funnels.length > 0 || appearances.length > 0)
277
+ .map((counters) => ({ ...counters, audience: counters.audience ?? DEFAULT_AUDIENCE_ID }));
278
+ const tallyStoreIn = (db, application) => {
180
279
  /**
181
- * Two upserts in one transaction.
280
+ * Three upserts per audience, every audience in one transaction.
182
281
  *
183
282
  * `ON CONFLICT … DO UPDATE SET x = table.x + excluded.x` is what makes
184
283
  * applying a rollup additive in one statement rather than a read, an add and
185
284
  * a write with a race in the middle. Two rollups running at once is not
186
285
  * hypothetical — a scheduled one and a manual one is the ordinary way it
187
286
  * happens — and this is the version that is correct when they do.
287
+ *
288
+ * **The transaction spans the audiences and not just the statements** (0316).
289
+ * A window folded per audience and written in separate transactions has a
290
+ * state between them where some audiences are durable and the rest are not,
291
+ * and the buffer still holds the window — so the next run adds the durable
292
+ * ones again, permanently and invisibly. One transaction removes the state.
188
293
  */
189
- apply: async ({ tallies, funnels }, at) => {
190
- if (tallies.length === 0 && funnels.length === 0)
294
+ const applyWindow = async (window, at) => {
295
+ const groups = writable(window);
296
+ if (groups.length === 0)
191
297
  return ok(undefined);
192
298
  const updatedAt = new Date(at);
193
299
  try {
194
300
  await db.transaction(async (tx) => {
195
- if (tallies.length > 0) {
196
- await tx
197
- .insert(loomReaderTallies)
198
- .values(tallies.map((tally) => ({
199
- treeId: tally.treeId,
200
- revision: tally.revision,
201
- nodeId: tally.nodeId,
202
- type: tally.type,
203
- views: tally.views,
204
- reached: tally.reached,
205
- engaged: tally.engaged,
206
- dwellMs: tally.dwellMs,
207
- activations: tally.activations,
208
- opens: tally.opens,
209
- closes: tally.closes,
210
- updatedAt,
211
- })))
212
- .onConflictDoUpdate({
213
- target: [loomReaderTallies.treeId, loomReaderTallies.revision, loomReaderTallies.nodeId],
214
- set: {
215
- type: sql `excluded.type`,
216
- views: sql `${loomReaderTallies.views} + excluded.views`,
217
- reached: sql `${loomReaderTallies.reached} + excluded.reached`,
218
- engaged: sql `${loomReaderTallies.engaged} + excluded.engaged`,
219
- dwellMs: sql `${loomReaderTallies.dwellMs} + excluded.dwell_ms`,
220
- activations: sql `${loomReaderTallies.activations} + excluded.activations`,
221
- opens: sql `${loomReaderTallies.opens} + excluded.opens`,
222
- closes: sql `${loomReaderTallies.closes} + excluded.closes`,
301
+ for (const { audience, tallies, funnels, appearances = [] } of groups) {
302
+ if (tallies.length > 0) {
303
+ await tx
304
+ .insert(loomReaderTallies)
305
+ .values(foldedBy(tallies, tallyKey, addTallies).map((tally) => ({
306
+ applicationId: application,
307
+ audienceId: audience,
308
+ treeId: tally.treeId,
309
+ revision: tally.revision,
310
+ nodeId: tally.nodeId,
311
+ type: tally.type,
312
+ views: tally.views,
313
+ reached: tally.reached,
314
+ engaged: tally.engaged,
315
+ dwellMs: tally.dwellMs,
316
+ activations: tally.activations,
317
+ opens: tally.opens,
318
+ closes: tally.closes,
319
+ completions: tally.completions,
223
320
  updatedAt,
224
- },
225
- });
226
- }
227
- if (funnels.length > 0) {
228
- await tx
229
- .insert(loomReaderFunnels)
230
- .values(funnels.map((answer) => ({
231
- treeId: answer.treeId,
232
- revision: answer.revision,
233
- fromNodeId: answer.pair.from.nodeId,
234
- fromKind: answer.pair.from.kind,
235
- toNodeId: answer.pair.to.nodeId,
236
- toKind: answer.pair.to.kind,
237
- reached: answer.reached,
238
- converted: answer.converted,
239
- updatedAt,
240
- })))
241
- .onConflictDoUpdate({
242
- target: [
243
- loomReaderFunnels.treeId,
244
- loomReaderFunnels.revision,
245
- loomReaderFunnels.fromNodeId,
246
- loomReaderFunnels.fromKind,
247
- loomReaderFunnels.toNodeId,
248
- loomReaderFunnels.toKind,
249
- ],
250
- set: {
251
- reached: sql `${loomReaderFunnels.reached} + excluded.reached`,
252
- converted: sql `${loomReaderFunnels.converted} + excluded.converted`,
321
+ })))
322
+ .onConflictDoUpdate({
323
+ target: [
324
+ loomReaderTallies.applicationId,
325
+ loomReaderTallies.audienceId,
326
+ loomReaderTallies.treeId,
327
+ loomReaderTallies.revision,
328
+ loomReaderTallies.nodeId,
329
+ ],
330
+ set: {
331
+ type: sql `excluded.type`,
332
+ views: sql `${loomReaderTallies.views} + excluded.views`,
333
+ reached: sql `${loomReaderTallies.reached} + excluded.reached`,
334
+ engaged: sql `${loomReaderTallies.engaged} + excluded.engaged`,
335
+ dwellMs: sql `${loomReaderTallies.dwellMs} + excluded.dwell_ms`,
336
+ activations: sql `${loomReaderTallies.activations} + excluded.activations`,
337
+ opens: sql `${loomReaderTallies.opens} + excluded.opens`,
338
+ closes: sql `${loomReaderTallies.closes} + excluded.closes`,
339
+ completions: sql `${loomReaderTallies.completions} + excluded.completions`,
340
+ updatedAt,
341
+ },
342
+ });
343
+ }
344
+ if (appearances.length > 0) {
345
+ /**
346
+ * In the same transaction as the tallies, because the two numbers a
347
+ * reading subtracts have to describe the same window: a page-view row
348
+ * that moved while the counters it is compared against did not would
349
+ * report a straddle that never happened.
350
+ */
351
+ await tx
352
+ .insert(loomReaderPageViews)
353
+ .values(foldedBy(appearances, pageViewKey, addPageViewCounts).map((count) => ({
354
+ applicationId: application,
355
+ audienceId: audience,
356
+ treeId: count.treeId,
357
+ revision: count.revision,
358
+ appearances: count.views,
253
359
  updatedAt,
254
- },
255
- });
360
+ foldedAt: updatedAt,
361
+ })))
362
+ .onConflictDoUpdate({
363
+ target: [
364
+ loomReaderPageViews.applicationId,
365
+ loomReaderPageViews.audienceId,
366
+ loomReaderPageViews.treeId,
367
+ loomReaderPageViews.revision,
368
+ ],
369
+ set: {
370
+ appearances: sql `${loomReaderPageViews.appearances} + excluded.appearances`,
371
+ updatedAt,
372
+ /**
373
+ * The fold's own timestamp, which only this writer sets (0274).
374
+ * The door's upsert below leaves the column out of its `set`
375
+ * entirely, so an arrival can never make a stalled collection
376
+ * look like a fresh one.
377
+ */
378
+ foldedAt: updatedAt,
379
+ },
380
+ });
381
+ }
382
+ if (funnels.length > 0) {
383
+ await tx
384
+ .insert(loomReaderFunnels)
385
+ .values(foldedBy(funnels, funnelKey, addFunnelAnswers).map((answer) => ({
386
+ applicationId: application,
387
+ audienceId: audience,
388
+ treeId: answer.treeId,
389
+ revision: answer.revision,
390
+ fromNodeId: answer.pair.from.nodeId,
391
+ fromKind: answer.pair.from.kind,
392
+ toNodeId: answer.pair.to.nodeId,
393
+ toKind: answer.pair.to.kind,
394
+ reached: answer.reached,
395
+ converted: answer.converted,
396
+ updatedAt,
397
+ })))
398
+ .onConflictDoUpdate({
399
+ target: [
400
+ loomReaderFunnels.applicationId,
401
+ loomReaderFunnels.audienceId,
402
+ loomReaderFunnels.treeId,
403
+ loomReaderFunnels.revision,
404
+ loomReaderFunnels.fromNodeId,
405
+ loomReaderFunnels.fromKind,
406
+ loomReaderFunnels.toNodeId,
407
+ loomReaderFunnels.toKind,
408
+ ],
409
+ set: {
410
+ reached: sql `${loomReaderFunnels.reached} + excluded.reached`,
411
+ converted: sql `${loomReaderFunnels.converted} + excluded.converted`,
412
+ updatedAt,
413
+ },
414
+ });
415
+ }
256
416
  }
257
417
  });
258
418
  return ok(undefined);
259
419
  }
260
420
  catch (cause) {
261
- return err(failure(cause, `could not apply ${tallies.length} tallies and ${funnels.length} funnels`));
421
+ const tallies = groups.reduce((total, group) => total + group.tallies.length, 0);
422
+ const funnels = groups.reduce((total, group) => total + group.funnels.length, 0);
423
+ return err(failure(cause, `could not apply ${tallies} tallies and ${funnels} funnels across ${groups.length} ${groups.length === 1 ? "audience" : "audiences"}`));
262
424
  }
263
- },
264
- tallies: async (request) => {
265
- try {
266
- const rows = await db.select().from(loomReaderTallies).where(within(loomReaderTallies, request));
267
- const parsed = z.array(storedTallySchema).safeParse(rows);
268
- return parsed.success
269
- ? ok(parsed.data)
270
- : err({
271
- code: "unavailable",
272
- detail: `a stored tally did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
425
+ };
426
+ return {
427
+ applyWindow,
428
+ apply: (counters, at, audience = DEFAULT_AUDIENCE_ID) => applyWindow([{ ...counters, audience }], at),
429
+ /**
430
+ * One upsert, additive in the statement, for the reason the regions are: this
431
+ * runs on the request path and two readers arriving together is the ordinary
432
+ * case rather than the unlucky one.
433
+ *
434
+ * It touches one column and leaves the other where it was, so a door and a
435
+ * rollup writing the same row at the same instant cannot lose each other's
436
+ * number.
437
+ *
438
+ * **`folded_at` is absent from the insert and from the `set`**, which is the
439
+ * whole of what makes it readable as a fold's age (0274): an arrival must
440
+ * never move it, and a row this write creates attests no fold rather than
441
+ * attesting one at the moment a reader arrived.
442
+ */
443
+ opened: async (openings, at, audience = DEFAULT_AUDIENCE_ID) => {
444
+ if (openings.length === 0)
445
+ return ok(undefined);
446
+ const updatedAt = new Date(at);
447
+ try {
448
+ await db
449
+ .insert(loomReaderPageViews)
450
+ .values(foldedBy(openings, pageViewKey, addPageViewCounts).map((count) => ({
451
+ applicationId: application,
452
+ audienceId: audience,
453
+ treeId: count.treeId,
454
+ revision: count.revision,
455
+ opened: count.views,
456
+ updatedAt,
457
+ })))
458
+ .onConflictDoUpdate({
459
+ target: [
460
+ loomReaderPageViews.applicationId,
461
+ loomReaderPageViews.audienceId,
462
+ loomReaderPageViews.treeId,
463
+ loomReaderPageViews.revision,
464
+ ],
465
+ set: {
466
+ opened: sql `${loomReaderPageViews.opened} + excluded.opened`,
467
+ updatedAt,
468
+ },
273
469
  });
470
+ return ok(undefined);
471
+ }
472
+ catch (cause) {
473
+ return err(failure(cause, `could not count ${openings.length} page views`));
474
+ }
475
+ },
476
+ tallies: async (request) => {
477
+ try {
478
+ const rows = await db.select().from(loomReaderTallies).where(within(loomReaderTallies, application, request));
479
+ const parsed = z.array(storedTallySchema).safeParse(rows);
480
+ return parsed.success
481
+ ? ok(parsed.data)
482
+ : err({
483
+ code: "unavailable",
484
+ detail: `a stored tally did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
485
+ });
486
+ }
487
+ catch (cause) {
488
+ return err(failure(cause, "could not read reader tallies"));
489
+ }
490
+ },
491
+ funnels: async (request) => {
492
+ try {
493
+ const rows = await db.select().from(loomReaderFunnels).where(within(loomReaderFunnels, application, request));
494
+ const parsed = z.array(storedFunnelSchema).safeParse(rows);
495
+ return parsed.success
496
+ ? ok(parsed.data)
497
+ : err({
498
+ code: "unavailable",
499
+ detail: `a stored funnel did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
500
+ });
501
+ }
502
+ catch (cause) {
503
+ return err(failure(cause, "could not read reader funnels"));
504
+ }
505
+ },
506
+ pageViews: async (request) => {
507
+ try {
508
+ const rows = await db
509
+ .select()
510
+ .from(loomReaderPageViews)
511
+ .where(within(loomReaderPageViews, application, request));
512
+ const parsed = z.array(storedPageViewsSchema).safeParse(rows);
513
+ return parsed.success
514
+ ? ok(parsed.data)
515
+ : err({
516
+ code: "unavailable",
517
+ detail: `a stored page-view count did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
518
+ });
519
+ }
520
+ catch (cause) {
521
+ return err(failure(cause, "could not read reader page views"));
522
+ }
523
+ },
524
+ };
525
+ };
526
+ const storedRegionSchema = z.object({
527
+ audienceId: audienceIdSchema,
528
+ treeId: treeIdSchema,
529
+ revision: z.number().int().nonnegative(),
530
+ /**
531
+ * Parsed on the way out like every other column, which here is a closed set
532
+ * of two-letter codes and one word. A row holding anything else was not
533
+ * written by this runtime, and reading it as a region would put it on a screen.
534
+ */
535
+ region: readerRegionSchema,
536
+ views: countSchema,
537
+ updatedAt: instantSchema,
538
+ });
539
+ /** Scoped on the same terms as the journal — see its note. */
540
+ export const postgresReaderRegionStore = (db, scope = {}) => regionStoreIn(db, scope.application ?? DEFAULT_APPLICATION_ID);
541
+ const regionStoreIn = (db, application) => ({
542
+ /**
543
+ * One upsert, additive in the statement, for the reason the tallies are: this
544
+ * runs on the request path and two deliveries arriving together is the
545
+ * ordinary case rather than the unlucky one.
546
+ */
547
+ count: async (counts, at, audience = DEFAULT_AUDIENCE_ID) => {
548
+ if (counts.length === 0)
549
+ return ok(undefined);
550
+ const updatedAt = new Date(at);
551
+ try {
552
+ await db
553
+ .insert(loomReaderRegions)
554
+ .values(foldedBy(counts, regionKey, addRegionCounts).map((count) => ({
555
+ applicationId: application,
556
+ audienceId: audience,
557
+ treeId: count.treeId,
558
+ revision: count.revision,
559
+ region: count.region,
560
+ views: count.views,
561
+ updatedAt,
562
+ })))
563
+ .onConflictDoUpdate({
564
+ target: [
565
+ loomReaderRegions.applicationId,
566
+ loomReaderRegions.audienceId,
567
+ loomReaderRegions.treeId,
568
+ loomReaderRegions.revision,
569
+ loomReaderRegions.region,
570
+ ],
571
+ set: {
572
+ views: sql `${loomReaderRegions.views} + excluded.views`,
573
+ updatedAt,
574
+ },
575
+ });
576
+ return ok(undefined);
274
577
  }
275
578
  catch (cause) {
276
- return err(failure(cause, "could not read reader tallies"));
579
+ return err(failure(cause, `could not count ${counts.length} reader regions`));
277
580
  }
278
581
  },
279
- funnels: async (request) => {
582
+ regions: async (request) => {
280
583
  try {
281
- const rows = await db.select().from(loomReaderFunnels).where(within(loomReaderFunnels, request));
282
- const parsed = z.array(storedFunnelSchema).safeParse(rows);
584
+ const rows = await db.select().from(loomReaderRegions).where(within(loomReaderRegions, application, request));
585
+ const parsed = z.array(storedRegionSchema).safeParse(rows);
283
586
  return parsed.success
284
587
  ? ok(parsed.data)
285
588
  : err({
286
589
  code: "unavailable",
287
- detail: `a stored funnel did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
590
+ detail: `a stored region did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
288
591
  });
289
592
  }
290
593
  catch (cause) {
291
- return err(failure(cause, "could not read reader funnels"));
594
+ return err(failure(cause, "could not read reader regions"));
292
595
  }
293
596
  },
294
597
  });