@jam-overture/loom 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -1,4 +1,4 @@
1
- import { and, asc, desc, eq, gt, lt, sql } from "drizzle-orm";
1
+ import { and, asc, desc, eq, gt, gte, isNotNull, isNull, lt, min, sql } from "drizzle-orm";
2
2
  import { z } from "zod";
3
3
  import { DEFAULT_AUDIENCE_ID, audienceIdSchema } from "../audience/audience.js";
4
4
  import { nodeIdSchema, treeIdSchema } from "../ids.js";
@@ -6,11 +6,12 @@ import { cursorPosition, pageEnds } from "../paging.js";
6
6
  import { primitiveTypeSchema } from "../primitive-type.js";
7
7
  import { DEFAULT_APPLICATION_ID, } from "../application/application.js";
8
8
  import { err, ok } from "../result.js";
9
- import { addFunnelAnswers, addPageViewCounts, addRegionCounts, addTallies, foldedBy, funnelKey, pageViewKey, regionKey, tallyKey, } from "./counters.js";
9
+ import { actedKey, addFunnelHourCounts, funnelHourKey, addActedCounts, addArrivalCounts, addFunnelAnswers, addPageViewCounts, addRegionCounts, addTallies, arrivalKey, foldedBy, funnelKey, pageViewKey, regionKey, tallyKey, } from "./counters.js";
10
+ import { arrivalHoursOf } from "./arrivals.js";
10
11
  import { clampReaderSignalLimit, } from "./journal.js";
11
12
  import { readerRegionSchema, } from "./region.js";
12
13
  import { readerSignalKindSchema, readerSignalSchema, viewKeySchema } from "./signal.js";
13
- import { loomReaderFunnels, loomReaderPageViews, loomReaderRegions, loomReaderSignals, loomReaderTallies, } from "./schema.js";
14
+ import { loomReaderActedHours, loomReaderArrivals, loomReaderFunnelHours, loomReaderFunnels, loomReaderPageViews, loomReaderRegions, loomReaderSignals, loomReaderTallies, } from "./schema.js";
14
15
  export * from "./migrate.js";
15
16
  /**
16
17
  * The Drizzle tables are **not** re-exported, unlike the journal's.
@@ -66,6 +67,14 @@ const receivedSchema = z.object({
66
67
  view: viewKeySchema.nullable().transform((value) => value ?? undefined),
67
68
  signals: z.array(readerSignalSchema).min(1),
68
69
  receivedAt: instantSchema,
70
+ /**
71
+ * `null` in the column, absent on the row — a delivery no fold has counted
72
+ * (0351). The same nullable-to-absent transform `view` takes, for the same
73
+ * reason: an optional field is how the rest of the subsystem spells *there is
74
+ * nothing here*, and two spellings of that is how a `null` comes to be read
75
+ * as a value.
76
+ */
77
+ foldedAt: instantSchema.nullable().transform((value) => value ?? undefined),
69
78
  });
70
79
  /**
71
80
  * `bigint` columns come back as strings from one driver and numbers from
@@ -190,9 +199,27 @@ const journalIn = (db, application) => ({
190
199
  view: loomReaderSignals.view,
191
200
  signals: loomReaderSignals.signals,
192
201
  receivedAt: loomReaderSignals.receivedAt,
202
+ foldedAt: loomReaderSignals.foldedAt,
193
203
  })
194
204
  .from(loomReaderSignals)
195
- .where(and(eq(loomReaderSignals.applicationId, application), request?.treeId === undefined ? undefined : eq(loomReaderSignals.treeId, request.treeId), from === undefined
205
+ .where(and(eq(loomReaderSignals.applicationId, application), request?.treeId === undefined ? undefined : eq(loomReaderSignals.treeId, request.treeId),
206
+ /**
207
+ * Served by the partial index where it is `false`, which is the
208
+ * fold's read and the one that would otherwise scan the kept window
209
+ * (0351).
210
+ */
211
+ request?.counted === undefined
212
+ ? undefined
213
+ : request.counted
214
+ ? isNotNull(loomReaderSignals.foldedAt)
215
+ : isNull(loomReaderSignals.foldedAt),
216
+ /**
217
+ * One page view's deliveries (0355), served by the partial index on
218
+ * the column. A request naming a key that no row carries is an
219
+ * empty page, which is what a page view whose rows have been swept
220
+ * is.
221
+ */
222
+ request?.view === undefined ? undefined : eq(loomReaderSignals.view, request.view), from === undefined
196
223
  ? undefined
197
224
  : direction === "older"
198
225
  ? lt(loomReaderSignals.seq, from)
@@ -223,6 +250,32 @@ const journalIn = (db, application) => ({
223
250
  return err(failure(cause, "could not read reader signals"));
224
251
  }
225
252
  },
253
+ /**
254
+ * One `UPDATE`, carrying its own idempotence in the `WHERE` (0351).
255
+ *
256
+ * `folded_at IS NULL` is what makes a repeat of this statement a no-op rather
257
+ * than a rewrite: the caller has already made the counters durable before it
258
+ * gets here, so a retry must not move an instant that a reading has been
259
+ * taken against. It is also what makes the reported count honest — rows this
260
+ * call stamped, not rows below the position.
261
+ *
262
+ * Scoped to the application like every other statement in this journal: `seq`
263
+ * is database-wide, so an unscoped `UPDATE` would stamp another deployment's
264
+ * uncounted deliveries and make them eligible for its retention sweep.
265
+ */
266
+ counted: async ({ before, at }) => {
267
+ try {
268
+ const stamped = await db
269
+ .update(loomReaderSignals)
270
+ .set({ foldedAt: new Date(at) })
271
+ .where(and(eq(loomReaderSignals.applicationId, application), lt(loomReaderSignals.seq, before), isNull(loomReaderSignals.foldedAt)))
272
+ .returning({ seq: loomReaderSignals.seq });
273
+ return ok({ counted: stamped.length });
274
+ }
275
+ catch (cause) {
276
+ return err(failure(cause, `could not record the fold of reader signals below ${before}`));
277
+ }
278
+ },
226
279
  /** The count comes from the returned rows, because the two drivers report `rowCount` differently. */
227
280
  forget: async ({ before }) => {
228
281
  try {
@@ -256,6 +309,69 @@ const journalIn = (db, application) => ({
256
309
  * and a reading that compares two audiences is the point of serving two.
257
310
  */
258
311
  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));
312
+ /**
313
+ * An hour comes back as a `Date` and is read as the instant it began, in
314
+ * milliseconds — which is what the vocabulary above this boundary counts in,
315
+ * because an hour is a bucket arithmetic is done on rather than a label.
316
+ */
317
+ const hourSchema = z
318
+ .union([z.date(), z.string()])
319
+ .transform((value) => (value instanceof Date ? value : new Date(value)))
320
+ .refine((value) => Number.isFinite(value.getTime()), "is not an instant")
321
+ .transform((value) => value.getTime());
322
+ const storedArrivalSchema = z.object({
323
+ audienceId: audienceIdSchema,
324
+ treeId: treeIdSchema,
325
+ revision: z.number().int().nonnegative(),
326
+ hour: hourSchema,
327
+ views: countSchema,
328
+ updatedAt: instantSchema,
329
+ });
330
+ /**
331
+ * The four end columns become the pair the reading matches on, exactly as the
332
+ * funnel row's do — one spelling of what the two ends are, so the hourly slice
333
+ * and the row it slices cannot disagree about which question they answer.
334
+ */
335
+ const storedFunnelHourSchema = z
336
+ .object({
337
+ audienceId: audienceIdSchema,
338
+ treeId: treeIdSchema,
339
+ revision: z.number().int().nonnegative(),
340
+ fromNodeId: nodeIdSchema,
341
+ fromKind: readerSignalKindSchema,
342
+ toNodeId: nodeIdSchema,
343
+ toKind: readerSignalKindSchema,
344
+ hour: hourSchema,
345
+ reached: countSchema,
346
+ converted: countSchema,
347
+ updatedAt: instantSchema,
348
+ })
349
+ .transform((row) => ({
350
+ audienceId: row.audienceId,
351
+ treeId: row.treeId,
352
+ revision: row.revision,
353
+ pair: {
354
+ from: { nodeId: row.fromNodeId, kind: row.fromKind },
355
+ to: { nodeId: row.toNodeId, kind: row.toKind },
356
+ },
357
+ hour: row.hour,
358
+ reached: row.reached,
359
+ converted: row.converted,
360
+ updatedAt: row.updatedAt,
361
+ }));
362
+ const storedActedSchema = z.object({
363
+ audienceId: audienceIdSchema,
364
+ treeId: treeIdSchema,
365
+ revision: z.number().int().nonnegative(),
366
+ nodeId: nodeIdSchema,
367
+ type: primitiveTypeSchema,
368
+ hour: hourSchema,
369
+ activations: countSchema,
370
+ opens: countSchema,
371
+ closes: countSchema,
372
+ completions: countSchema,
373
+ updatedAt: instantSchema,
374
+ });
259
375
  /** Scoped on the same terms as the journal — see its note. */
260
376
  export const postgresReaderTallyStore = (db, scope = {}) => tallyStoreIn(db, scope.application ?? DEFAULT_APPLICATION_ID);
261
377
  /**
@@ -273,7 +389,11 @@ export const postgresReaderTallyStore = (db, scope = {}) => tallyStoreIn(db, sco
273
389
  * `counters.ts` was bitten by.
274
390
  */
275
391
  const writable = (window) => window
276
- .filter(({ tallies, funnels, appearances = [] }) => tallies.length > 0 || funnels.length > 0 || appearances.length > 0)
392
+ .filter(({ tallies, funnels, appearances = [], acted = [], funnelHours = [] }) => tallies.length > 0 ||
393
+ funnels.length > 0 ||
394
+ appearances.length > 0 ||
395
+ acted.length > 0 ||
396
+ funnelHours.length > 0)
277
397
  .map((counters) => ({ ...counters, audience: counters.audience ?? DEFAULT_AUDIENCE_ID }));
278
398
  const tallyStoreIn = (db, application) => {
279
399
  /**
@@ -298,7 +418,7 @@ const tallyStoreIn = (db, application) => {
298
418
  const updatedAt = new Date(at);
299
419
  try {
300
420
  await db.transaction(async (tx) => {
301
- for (const { audience, tallies, funnels, appearances = [] } of groups) {
421
+ for (const { audience, tallies, funnels, appearances = [], acted = [], funnelHours = [], } of groups) {
302
422
  if (tallies.length > 0) {
303
423
  await tx
304
424
  .insert(loomReaderTallies)
@@ -341,6 +461,48 @@ const tallyStoreIn = (db, application) => {
341
461
  },
342
462
  });
343
463
  }
464
+ if (acted.length > 0) {
465
+ /**
466
+ * The hourly slice of the four occurrence counters above
467
+ * (`acted.ts`), in the same transaction and from the same fold —
468
+ * so a part's hours sum to the part's own counters rather than to
469
+ * whatever survived a second write.
470
+ */
471
+ await tx
472
+ .insert(loomReaderActedHours)
473
+ .values(foldedBy(acted, actedKey, addActedCounts).map((count) => ({
474
+ applicationId: application,
475
+ audienceId: audience,
476
+ treeId: count.treeId,
477
+ revision: count.revision,
478
+ nodeId: count.nodeId,
479
+ hour: new Date(count.hour),
480
+ type: count.type,
481
+ activations: count.activations,
482
+ opens: count.opens,
483
+ closes: count.closes,
484
+ completions: count.completions,
485
+ updatedAt,
486
+ })))
487
+ .onConflictDoUpdate({
488
+ target: [
489
+ loomReaderActedHours.applicationId,
490
+ loomReaderActedHours.audienceId,
491
+ loomReaderActedHours.treeId,
492
+ loomReaderActedHours.revision,
493
+ loomReaderActedHours.nodeId,
494
+ loomReaderActedHours.hour,
495
+ ],
496
+ set: {
497
+ type: sql `excluded.type`,
498
+ activations: sql `${loomReaderActedHours.activations} + excluded.activations`,
499
+ opens: sql `${loomReaderActedHours.opens} + excluded.opens`,
500
+ closes: sql `${loomReaderActedHours.closes} + excluded.closes`,
501
+ completions: sql `${loomReaderActedHours.completions} + excluded.completions`,
502
+ updatedAt,
503
+ },
504
+ });
505
+ }
344
506
  if (appearances.length > 0) {
345
507
  /**
346
508
  * In the same transaction as the tallies, because the two numbers a
@@ -413,6 +575,48 @@ const tallyStoreIn = (db, application) => {
413
575
  },
414
576
  });
415
577
  }
578
+ if (funnelHours.length > 0) {
579
+ /**
580
+ * The hourly cut of the answers above (`funnel-hours.ts`), in the
581
+ * same transaction and from the same fold — so a pair's hours sum
582
+ * to the pair's own row rather than to whatever survived a second
583
+ * write.
584
+ */
585
+ await tx
586
+ .insert(loomReaderFunnelHours)
587
+ .values(foldedBy(funnelHours, funnelHourKey, addFunnelHourCounts).map((count) => ({
588
+ applicationId: application,
589
+ audienceId: audience,
590
+ treeId: count.treeId,
591
+ revision: count.revision,
592
+ fromNodeId: count.pair.from.nodeId,
593
+ fromKind: count.pair.from.kind,
594
+ toNodeId: count.pair.to.nodeId,
595
+ toKind: count.pair.to.kind,
596
+ hour: new Date(count.hour),
597
+ reached: count.reached,
598
+ converted: count.converted,
599
+ updatedAt,
600
+ })))
601
+ .onConflictDoUpdate({
602
+ target: [
603
+ loomReaderFunnelHours.applicationId,
604
+ loomReaderFunnelHours.audienceId,
605
+ loomReaderFunnelHours.treeId,
606
+ loomReaderFunnelHours.revision,
607
+ loomReaderFunnelHours.fromNodeId,
608
+ loomReaderFunnelHours.fromKind,
609
+ loomReaderFunnelHours.toNodeId,
610
+ loomReaderFunnelHours.toKind,
611
+ loomReaderFunnelHours.hour,
612
+ ],
613
+ set: {
614
+ reached: sql `${loomReaderFunnelHours.reached} + excluded.reached`,
615
+ converted: sql `${loomReaderFunnelHours.converted} + excluded.converted`,
616
+ updatedAt,
617
+ },
618
+ });
619
+ }
416
620
  }
417
621
  });
418
622
  return ok(undefined);
@@ -443,29 +647,66 @@ const tallyStoreIn = (db, application) => {
443
647
  opened: async (openings, at, audience = DEFAULT_AUDIENCE_ID) => {
444
648
  if (openings.length === 0)
445
649
  return ok(undefined);
650
+ const hours = arrivalHoursOf(openings, at);
651
+ if (!hours.ok)
652
+ return hours;
446
653
  const updatedAt = new Date(at);
447
654
  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`,
655
+ /**
656
+ * **Two upserts in one transaction**, which is the pair the interface
657
+ * promises: the revision's total and the hour it arrived in are the
658
+ * same arrivals under two keys, and a door that moved one without the
659
+ * other would leave an hourly chart that does not sum to the page-view
660
+ * count it is drawn beside — permanently, because a count cannot be
661
+ * uncounted (0158).
662
+ */
663
+ await db.transaction(async (tx) => {
664
+ await tx
665
+ .insert(loomReaderPageViews)
666
+ .values(foldedBy(openings, pageViewKey, addPageViewCounts).map((count) => ({
667
+ applicationId: application,
668
+ audienceId: audience,
669
+ treeId: count.treeId,
670
+ revision: count.revision,
671
+ opened: count.views,
672
+ updatedAt,
673
+ })))
674
+ .onConflictDoUpdate({
675
+ target: [
676
+ loomReaderPageViews.applicationId,
677
+ loomReaderPageViews.audienceId,
678
+ loomReaderPageViews.treeId,
679
+ loomReaderPageViews.revision,
680
+ ],
681
+ set: {
682
+ opened: sql `${loomReaderPageViews.opened} + excluded.opened`,
683
+ updatedAt,
684
+ },
685
+ });
686
+ await tx
687
+ .insert(loomReaderArrivals)
688
+ .values(foldedBy(hours.value, arrivalKey, addArrivalCounts).map((count) => ({
689
+ applicationId: application,
690
+ audienceId: audience,
691
+ treeId: count.treeId,
692
+ revision: count.revision,
693
+ hour: new Date(count.hour),
694
+ views: count.views,
467
695
  updatedAt,
468
- },
696
+ })))
697
+ .onConflictDoUpdate({
698
+ target: [
699
+ loomReaderArrivals.applicationId,
700
+ loomReaderArrivals.audienceId,
701
+ loomReaderArrivals.treeId,
702
+ loomReaderArrivals.revision,
703
+ loomReaderArrivals.hour,
704
+ ],
705
+ set: {
706
+ views: sql `${loomReaderArrivals.views} + excluded.views`,
707
+ updatedAt,
708
+ },
709
+ });
469
710
  });
470
711
  return ok(undefined);
471
712
  }
@@ -521,6 +762,139 @@ const tallyStoreIn = (db, application) => {
521
762
  return err(failure(cause, "could not read reader page views"));
522
763
  }
523
764
  },
765
+ /**
766
+ * Two statements and one call: the hours in the range, and the first hour
767
+ * the same narrowing has at all.
768
+ *
769
+ * The second is a `MIN` over an index whose leading column is the
770
+ * application, so it costs a lookup rather than a scan — and it is the only
771
+ * way to tell an empty range apart from a deployment that was not counting
772
+ * through it. Not in one statement with a window function, because the two
773
+ * answers have different shapes and a row carrying both would make every
774
+ * caller unpack a figure repeated on every row.
775
+ */
776
+ arrivals: async (request) => {
777
+ const scope = within(loomReaderArrivals, application, request);
778
+ try {
779
+ const rows = await db
780
+ .select()
781
+ .from(loomReaderArrivals)
782
+ .where(and(scope, request?.from === undefined
783
+ ? undefined
784
+ : gte(loomReaderArrivals.hour, new Date(request.from)), request?.to === undefined
785
+ ? undefined
786
+ : lt(loomReaderArrivals.hour, new Date(request.to))));
787
+ const parsed = z.array(storedArrivalSchema).safeParse(rows);
788
+ if (!parsed.success) {
789
+ return err({
790
+ code: "unavailable",
791
+ detail: `a stored arrival did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
792
+ });
793
+ }
794
+ const [earliest] = await db
795
+ .select({ hour: min(loomReaderArrivals.hour) })
796
+ .from(loomReaderArrivals)
797
+ .where(scope);
798
+ const begins = hourSchema.safeParse(earliest?.hour);
799
+ return ok({
800
+ hours: parsed.data,
801
+ ...(begins.success ? { begins: begins.data } : {}),
802
+ });
803
+ }
804
+ catch (cause) {
805
+ return err(failure(cause, "could not read reader arrivals"));
806
+ }
807
+ },
808
+ /**
809
+ * The rows in the range and the first hour the scope ever counted, as the
810
+ * arrivals read above answers them — with the part in **both** narrowings.
811
+ *
812
+ * A goal made today over a deployment that has counted for a year must
813
+ * report the first hour *that part* was acted in; taking the beginning over
814
+ * the deployment would draw a year of noughts behind a figure that has
815
+ * existed for an afternoon.
816
+ */
817
+ acted: async (request) => {
818
+ const scope = and(within(loomReaderActedHours, application, request), request?.nodeId === undefined ? undefined : eq(loomReaderActedHours.nodeId, request.nodeId));
819
+ try {
820
+ const rows = await db
821
+ .select()
822
+ .from(loomReaderActedHours)
823
+ .where(and(scope, request?.from === undefined
824
+ ? undefined
825
+ : gte(loomReaderActedHours.hour, new Date(request.from)), request?.to === undefined
826
+ ? undefined
827
+ : lt(loomReaderActedHours.hour, new Date(request.to))));
828
+ const parsed = z.array(storedActedSchema).safeParse(rows);
829
+ if (!parsed.success) {
830
+ return err({
831
+ code: "unavailable",
832
+ detail: `a stored action hour did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
833
+ });
834
+ }
835
+ const [earliest] = await db
836
+ .select({ hour: min(loomReaderActedHours.hour) })
837
+ .from(loomReaderActedHours)
838
+ .where(scope);
839
+ const begins = hourSchema.safeParse(earliest?.hour);
840
+ return ok({
841
+ hours: parsed.data,
842
+ ...(begins.success ? { begins: begins.data } : {}),
843
+ });
844
+ }
845
+ catch (cause) {
846
+ return err(failure(cause, "could not read what readers did by hour"));
847
+ }
848
+ },
849
+ /**
850
+ * The same two answers again, narrowed to one funnel as well.
851
+ *
852
+ * The pair narrows **both** halves, for the reason the part does on the
853
+ * read above: a step set this afternoon on a deployment that has counted
854
+ * for a year must report that it has been measurable since this afternoon,
855
+ * or a comparison of two fortnights would draw a fortnight of noughts
856
+ * before the question existed and call the step a collapse.
857
+ *
858
+ * `pages` on a requested pair is not a narrowing and is not read: a scope
859
+ * decides which rows a fold writes and is no part of what a row means
860
+ * (0418), so a scoped question and an unscoped one are the same row and the
861
+ * same read.
862
+ */
863
+ funnelHours: async (request) => {
864
+ const pair = request?.pair;
865
+ const scope = and(within(loomReaderFunnelHours, application, request), pair === undefined
866
+ ? undefined
867
+ : and(eq(loomReaderFunnelHours.fromNodeId, pair.from.nodeId), eq(loomReaderFunnelHours.fromKind, pair.from.kind), eq(loomReaderFunnelHours.toNodeId, pair.to.nodeId), eq(loomReaderFunnelHours.toKind, pair.to.kind)));
868
+ try {
869
+ const rows = await db
870
+ .select()
871
+ .from(loomReaderFunnelHours)
872
+ .where(and(scope, request?.from === undefined
873
+ ? undefined
874
+ : gte(loomReaderFunnelHours.hour, new Date(request.from)), request?.to === undefined
875
+ ? undefined
876
+ : lt(loomReaderFunnelHours.hour, new Date(request.to))));
877
+ const parsed = z.array(storedFunnelHourSchema).safeParse(rows);
878
+ if (!parsed.success) {
879
+ return err({
880
+ code: "unavailable",
881
+ detail: `a stored funnel hour did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
882
+ });
883
+ }
884
+ const [earliest] = await db
885
+ .select({ hour: min(loomReaderFunnelHours.hour) })
886
+ .from(loomReaderFunnelHours)
887
+ .where(scope);
888
+ const begins = hourSchema.safeParse(earliest?.hour);
889
+ return ok({
890
+ hours: parsed.data,
891
+ ...(begins.success ? { begins: begins.data } : {}),
892
+ });
893
+ }
894
+ catch (cause) {
895
+ return err(failure(cause, "could not read a funnel by hour"));
896
+ }
897
+ },
524
898
  };
525
899
  };
526
900
  const storedRegionSchema = z.object({
@@ -190,7 +190,7 @@ export type RegionReading = {
190
190
  };
191
191
  export type RegionReadingOptions = {
192
192
  /** Raised above {@link DEFAULT_REGION_FLOOR}; a smaller number is the default. */
193
- readonly floor?: number;
193
+ readonly floor?: number | undefined;
194
194
  };
195
195
  /**
196
196
  * Rows from the store, read as something a screen may show.
@@ -1,18 +1,18 @@
1
- import type { CollectionOutcome } from "./collect.js";
1
+ import type { ExpiryOutcome } from "./expire.js";
2
2
  import type { DeliveryRetention } from "./notice.js";
3
3
  /**
4
4
  * Whether the deployment keeps the retention ceiling it publishes to its
5
5
  * readers.
6
6
  *
7
- * A notice tells the reader two things about a delivery's life: the age it
8
- * ripens at, which is this framework's own number, and how often the deployment
9
- * sweeps the ripe ones away, which is a claim about a cron nobody here can see
10
- * (0320). The two add to a ceiling — *gone within 70 minutes of arriving* — and
11
- * a deployment that states ten minutes and sweeps weekly publishes that
12
- * sentence to every reader of its privacy page with nothing behind it.
7
+ * A notice tells the reader three things about a delivery's life: the age it is
8
+ * counted at and the age it is deleted at, which are this deployment's own
9
+ * numbers, and how often its sweep runs, which is a claim about a cron nobody
10
+ * here can see (0320, 0351). They make a ceiling — *gone within 31 days of
11
+ * arriving* — and a deployment that states a day and sweeps monthly publishes
12
+ * that sentence to every reader of its privacy page with nothing behind it.
13
13
  *
14
- * **The evidence is already in the sweep's own hands.** A run scans the buffer
15
- * from its oldest end, so the age of the oldest delivery still waiting is a
14
+ * **The evidence is already in the sweep's own hands.** A run scans the table
15
+ * from its oldest end, so the age of the oldest delivery still there is a
16
16
  * number every run has and none of them reported. If that age is past the
17
17
  * ceiling, then a delivery existed that readers were told was gone — and it
18
18
  * existed for however long the gap is, whatever this run then deletes.
@@ -20,6 +20,15 @@ import type { DeliveryRetention } from "./notice.js";
20
20
  * So the check costs no read, no column, no byte on any wire and nothing in a
21
21
  * browser: it is a subtraction over what a sweep already looked at.
22
22
  *
23
+ * **It is the expiry run's evidence, not the fold's** (0351). Until 5 November
24
+ * the fold was the deletion, so the run that counted a window was also the run
25
+ * whose scan proved when deliveries went; now counting and deleting are two
26
+ * operations with two windows, and the published ceiling is about the second.
27
+ * Handing this the fold's outcome would judge a promise about deletion against
28
+ * a figure that measures how far behind counting is — which on a healthy
29
+ * deployment is minutes, so the check would read *kept* while a broken expiry
30
+ * cron kept everything for ever.
31
+ *
23
32
  * ## It is beside the notice and never inside it
24
33
  *
25
34
  * `collectionNoticeOf` is a pure function of a deployment's configuration and
@@ -57,22 +66,22 @@ export type RetentionPromise =
57
66
  /**
58
67
  * The run read no delivery, so nothing here says how old the oldest one is.
59
68
  *
60
- * Either it never reached the buffer — refused on its window, or the store
61
- * was unavailable — or the one instant it needed could not be read. A buffer
62
- * the sweep cannot see is a promise nothing can speak for, and the honest
63
- * answer is silence rather than *kept*.
69
+ * Either it never reached the table — refused on its window, or the store was
70
+ * unavailable — or the one instant it needed could not be read. A table the
71
+ * sweep cannot see is a promise nothing can speak for, and the honest answer
72
+ * is silence rather than *kept*.
64
73
  */
65
74
  | {
66
75
  readonly state: "unread";
67
76
  }
68
77
  /**
69
- * Nothing in the buffer is old enough to count, so nothing in it can be past
78
+ * Nothing in the table is old enough to delete, so nothing in it can be past
70
79
  * the ceiling.
71
80
  *
72
81
  * The strongest of the three quiet answers and the only one that is a proof.
73
- * A scan runs from the oldest end, so a run that found nothing ripe found
74
- * every delivery younger than the ripeness window — and the ceiling is that
75
- * window plus a sweep, which is longer. An empty buffer lands here too, for
82
+ * A scan runs from the oldest end, so a run that found nothing expirable
83
+ * found every delivery younger than the kept window — and the ceiling is that
84
+ * window plus a sweep, which is longer. An empty table lands here too, for
76
85
  * the same reason and with nothing waiting.
77
86
  */
78
87
  | {
@@ -88,9 +97,9 @@ export type RetentionPromise =
88
97
  */
89
98
  | {
90
99
  readonly state: "kept";
91
- /** How old the oldest delivery still in the buffer was, in milliseconds. */
100
+ /** How old the oldest delivery still in the table was, in milliseconds. */
92
101
  readonly oldestMs: number;
93
- /** The ceiling the notice publishes: the ripeness window plus one sweep. */
102
+ /** The ceiling the notice publishes: the later of the two windows plus one sweep. */
94
103
  readonly goneWithinMs: number;
95
104
  }
96
105
  /**
@@ -109,9 +118,22 @@ export type RetentionPromise =
109
118
  readonly goneWithinMs: number;
110
119
  /** How far past the ceiling the oldest delivery is. */
111
120
  readonly byMs: number;
121
+ /**
122
+ * Whether what is holding the oldest delivery is that no fold has counted
123
+ * it (`expire.ts`).
124
+ *
125
+ * The gap is real either way and this does not soften it — a delivery
126
+ * readers were told was gone is still there. What it does is name the
127
+ * remedy, which in this one case is not the expiry sweep's: nothing may
128
+ * delete an uncounted delivery, so a deployment whose collection has
129
+ * stopped breaks its retention promise by not counting, and running the
130
+ * deletion more often would change nothing.
131
+ */
132
+ readonly uncounted: boolean;
112
133
  };
113
134
  /**
114
- * Judge one sweep's own evidence against the ceiling its deployment publishes.
135
+ * Judge one expiry sweep's own evidence against the ceiling its deployment
136
+ * publishes.
115
137
  *
116
138
  * The retention is taken whole — the same `Pick` of the notice the reader's
117
139
  * sentence is built from (0320) — so the ceiling judged here is the ceiling
@@ -128,7 +150,7 @@ export type RetentionPromise =
128
150
  * ceiling, which is how the stall check answers a clock that disagrees with
129
151
  * itself (0274).
130
152
  */
131
- export declare const retentionPromiseOf: (outcome: CollectionOutcome, retention: DeliveryRetention) => RetentionPromise;
153
+ export declare const retentionPromiseOf: (outcome: ExpiryOutcome, retention: DeliveryRetention) => RetentionPromise;
132
154
  /**
133
155
  * One line for the operator who runs the sweep, because they are the only
134
156
  * person who can close the gap.