@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,6 +1,6 @@
1
1
  import type { LoomDatabase } from "../store/database.js";
2
2
  /**
3
- * Creating the five reader-signal tables, with row level security switched on.
3
+ * Creating the seven reader-signal tables, with row level security switched on.
4
4
  *
5
5
  * The same shape as the store's and the journal's migrations, and here for the
6
6
  * same reason: a DDL statement that lives in a document is a DDL statement a
@@ -10,11 +10,12 @@ import type { LoomDatabase } from "../store/database.js";
10
10
  * Nothing in these tables identifies a reader — that is 0146's whole argument —
11
11
  * but the buffer holds view keys, and a view key plus another deployment's rows
12
12
  * is the only combination in Loom that could correlate anything across a
13
- * tenancy boundary. It expires within hours; the policy does not depend on
14
- * that.
13
+ * tenancy boundary. It used to expire within hours and now expires within the
14
+ * window the deployment states, thirty days by default (0349, 0351); the policy
15
+ * never depended on that and now carries more of the weight.
15
16
  *
16
17
  * Every table is led by `application_id` (0269). The backfill is the column
17
- * default rather than an `UPDATE`: these five never carried `project_id`, so
18
+ * default rather than an `UPDATE`: these seven never carried `project_id`, so
18
19
  * there is no earlier spelling to correct the way `APPLICATION_ID_MIGRATION`
19
20
  * corrects the store's — rows that predate the column belong to the deployment
20
21
  * that wrote them, which is what `app_default` names.
@@ -29,7 +30,7 @@ import type { LoomDatabase } from "../store/database.js";
29
30
  * reads the buffer by audience.
30
31
  */
31
32
  /**
32
- * The five tables, as statements a host can run.
33
+ * The seven tables, as statements a host can run.
33
34
  *
34
35
  * One statement per entry for the same reason the store's DDL is a list: a
35
36
  * driver may refuse several commands in a single prepared statement, and
@@ -1,6 +1,6 @@
1
1
  import { sql } from "drizzle-orm";
2
2
  /**
3
- * Creating the five reader-signal tables, with row level security switched on.
3
+ * Creating the seven reader-signal tables, with row level security switched on.
4
4
  *
5
5
  * The same shape as the store's and the journal's migrations, and here for the
6
6
  * same reason: a DDL statement that lives in a document is a DDL statement a
@@ -10,11 +10,12 @@ import { sql } from "drizzle-orm";
10
10
  * Nothing in these tables identifies a reader — that is 0146's whole argument —
11
11
  * but the buffer holds view keys, and a view key plus another deployment's rows
12
12
  * is the only combination in Loom that could correlate anything across a
13
- * tenancy boundary. It expires within hours; the policy does not depend on
14
- * that.
13
+ * tenancy boundary. It used to expire within hours and now expires within the
14
+ * window the deployment states, thirty days by default (0349, 0351); the policy
15
+ * never depended on that and now carries more of the weight.
15
16
  *
16
17
  * Every table is led by `application_id` (0269). The backfill is the column
17
- * default rather than an `UPDATE`: these five never carried `project_id`, so
18
+ * default rather than an `UPDATE`: these seven never carried `project_id`, so
18
19
  * there is no earlier spelling to correct the way `APPLICATION_ID_MIGRATION`
19
20
  * corrects the store's — rows that predate the column belong to the deployment
20
21
  * that wrote them, which is what `app_default` names.
@@ -29,7 +30,7 @@ import { sql } from "drizzle-orm";
29
30
  * reads the buffer by audience.
30
31
  */
31
32
  /**
32
- * The five tables, as statements a host can run.
33
+ * The seven tables, as statements a host can run.
33
34
  *
34
35
  * One statement per entry for the same reason the store's DDL is a list: a
35
36
  * driver may refuse several commands in a single prepared statement, and
@@ -46,8 +47,20 @@ export const READER_SIGNALS_DDL = [
46
47
  sent_at bigint NOT NULL,
47
48
  view text,
48
49
  signals jsonb NOT NULL,
49
- received_at timestamptz NOT NULL DEFAULT now()
50
+ received_at timestamptz NOT NULL DEFAULT now(),
51
+ folded_at timestamptz
50
52
  )`,
53
+ /**
54
+ * **When the fold counted the delivery**, for a deployment whose buffer
55
+ * predates the kept window (0351).
56
+ *
57
+ * Additive, nullable and undefaulted, and the absence is a state the readings
58
+ * publish: *not yet counted*. There is no backfill and none is wanted — a row
59
+ * still in this table on a deployment that upgrades was, by the old rule, one
60
+ * no fold had reached, and a backfill that guessed otherwise would make
61
+ * retention eligible to delete a delivery the counters never saw.
62
+ */
63
+ `ALTER TABLE loom_reader_signals ADD COLUMN IF NOT EXISTS folded_at timestamptz`,
51
64
  /**
52
65
  * **The application, for a database that predates it (0269).** The same
53
66
  * shape the store's tables take: the column is additive and defaulted, and
@@ -79,6 +92,36 @@ export const READER_SIGNALS_DDL = [
79
92
  `ALTER TABLE loom_reader_signals ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
80
93
  `DROP INDEX IF EXISTS loom_reader_signals_tree_seq_idx`,
81
94
  `CREATE INDEX IF NOT EXISTS loom_reader_signals_tree_seq_idx ON loom_reader_signals (application_id, tree_id, seq)`,
95
+ /**
96
+ * **The oldest end across every tree** (0351), which is where both sweeps
97
+ * start: the fold scans for the oldest uncounted delivery and retention for
98
+ * the oldest kept one.
99
+ *
100
+ * Created rather than inherited because the table's lifetime changed. An hour
101
+ * of deliveries is a cheap scan however it is served; thirty days of them,
102
+ * with a deployment invited to state more, is not.
103
+ */
104
+ `CREATE INDEX IF NOT EXISTS loom_reader_signals_seq_idx ON loom_reader_signals (application_id, seq)`,
105
+ /**
106
+ * **The uncounted prefix** (0351), which is the fold's own read and the one
107
+ * index here that is partial.
108
+ *
109
+ * It is partial because the set it serves is bounded by the collection window
110
+ * and the rest of the table is not: on a deployment folding every hour and
111
+ * keeping thirty days, this covers about a seven-hundredth of the rows, and
112
+ * it shrinks to nothing every time the sweep runs. An index on `folded_at`
113
+ * across the whole table would be one entry per kept delivery to answer a
114
+ * question only ever asked about the newest few.
115
+ */
116
+ `CREATE INDEX IF NOT EXISTS loom_reader_signals_uncounted_idx ON loom_reader_signals (application_id, seq) WHERE folded_at IS NULL`,
117
+ /**
118
+ * **One page view's deliveries** (0355), which is the *Events* drawer's read.
119
+ *
120
+ * Partial for the reason the uncounted index is partial, though the set it
121
+ * leaves out is the other one: a delivery that names no page view is never
122
+ * looked up by one, so an entry for it would be paid for and never read.
123
+ */
124
+ `CREATE INDEX IF NOT EXISTS loom_reader_signals_view_idx ON loom_reader_signals (application_id, view) WHERE view IS NOT NULL`,
82
125
  `ALTER TABLE loom_reader_signals ENABLE ROW LEVEL SECURITY`,
83
126
  `CREATE TABLE IF NOT EXISTS loom_reader_tallies (
84
127
  application_id text NOT NULL DEFAULT 'app_default',
@@ -185,6 +228,107 @@ export const READER_SIGNALS_DDL = [
185
228
  `ALTER TABLE loom_reader_page_views DROP CONSTRAINT IF EXISTS loom_reader_page_views_pkey`,
186
229
  `ALTER TABLE loom_reader_page_views ADD PRIMARY KEY (application_id, audience_id, tree_id, revision)`,
187
230
  `ALTER TABLE loom_reader_page_views ENABLE ROW LEVEL SECURITY`,
231
+ /**
232
+ * **When the page views began**, which is the sixth table and the first
233
+ * here with a clock in its key (`arrivals.ts`); the seventh below is the
234
+ * other.
235
+ *
236
+ * No `ALTER` beside it and no backfill, which is the one thing about this
237
+ * table an operator has to know: nothing but this counter ever knew which
238
+ * hour an arrival was in, so a deployment that upgrades starts counting hours
239
+ * from the moment it runs this and has no earlier ones. The reading publishes
240
+ * that as the hour counting began, so a chart over thirty days on a
241
+ * deployment that has counted for a week draws a week and says so rather than
242
+ * drawing three empty weeks.
243
+ */
244
+ `CREATE TABLE IF NOT EXISTS loom_reader_arrivals (
245
+ application_id text NOT NULL DEFAULT 'app_default',
246
+ audience_id text NOT NULL DEFAULT 'aud_everyone',
247
+ tree_id text NOT NULL,
248
+ revision integer NOT NULL,
249
+ hour timestamptz NOT NULL,
250
+ views bigint NOT NULL,
251
+ updated_at timestamptz NOT NULL,
252
+ PRIMARY KEY (application_id, audience_id, tree_id, revision, hour)
253
+ )`,
254
+ /**
255
+ * **Every tree of one application, by hour**, which is the deployment-wide
256
+ * chart. The primary key already serves a reading of one page, because that
257
+ * read names the tree and the revision.
258
+ */
259
+ `CREATE INDEX IF NOT EXISTS loom_reader_arrivals_hour_idx ON loom_reader_arrivals (application_id, hour)`,
260
+ `ALTER TABLE loom_reader_arrivals ENABLE ROW LEVEL SECURITY`,
261
+ /**
262
+ * **What readers did to a part, by the hour they did it in**, which is the
263
+ * seventh table and the second with a clock in its key (`acted.ts`).
264
+ *
265
+ * No `ALTER` beside it and no backfill, for the reason the sixth table has
266
+ * none: nothing but this counter ever knew which hour a press was in, so a
267
+ * deployment that upgrades starts counting from the moment it runs this. The
268
+ * reading publishes the hour counting began, so a goal's figure over thirty
269
+ * days on a deployment that has counted for a week draws a week and says so.
270
+ */
271
+ `CREATE TABLE IF NOT EXISTS loom_reader_acted_hours (
272
+ application_id text NOT NULL DEFAULT 'app_default',
273
+ audience_id text NOT NULL DEFAULT 'aud_everyone',
274
+ tree_id text NOT NULL,
275
+ revision integer NOT NULL,
276
+ node_id text NOT NULL,
277
+ hour timestamptz NOT NULL,
278
+ type text NOT NULL,
279
+ activations bigint NOT NULL DEFAULT 0,
280
+ opens bigint NOT NULL DEFAULT 0,
281
+ closes bigint NOT NULL DEFAULT 0,
282
+ completions bigint NOT NULL DEFAULT 0,
283
+ updated_at timestamptz NOT NULL,
284
+ PRIMARY KEY (application_id, audience_id, tree_id, revision, node_id, hour)
285
+ )`,
286
+ /**
287
+ * **One part of one page over a range**, which is a goal's series: the
288
+ * primary key cannot serve it, because a goal names the tree and the part and
289
+ * neither of the two columns between them.
290
+ */
291
+ `CREATE INDEX IF NOT EXISTS loom_reader_acted_part_idx ON loom_reader_acted_hours (application_id, tree_id, node_id, hour)`,
292
+ /** **Every part of one application, by hour**, which is the deployment-wide reading. */
293
+ `CREATE INDEX IF NOT EXISTS loom_reader_acted_hour_idx ON loom_reader_acted_hours (application_id, hour)`,
294
+ `ALTER TABLE loom_reader_acted_hours ENABLE ROW LEVEL SECURITY`,
295
+ /**
296
+ * **A funnel pair's answer, by the hour the readers in it entered the
297
+ * funnel**, which is the eighth table and the third with a clock in its key
298
+ * (`funnel-hours.ts`).
299
+ *
300
+ * No `ALTER` beside it and no backfill, for the reason the two tables above
301
+ * have none: nothing but this counter ever knew which hour a reach was in,
302
+ * and the view keys that would be needed to work it out afterwards are gone
303
+ * with the window they were folded from (0146). A deployment that upgrades
304
+ * starts counting from the moment it runs this, and the reading publishes
305
+ * the hour counting began — so a step compared over two fortnights on a
306
+ * deployment that has counted for a week draws a week and says so.
307
+ */
308
+ `CREATE TABLE IF NOT EXISTS loom_reader_funnel_hours (
309
+ application_id text NOT NULL DEFAULT 'app_default',
310
+ audience_id text NOT NULL DEFAULT 'aud_everyone',
311
+ tree_id text NOT NULL,
312
+ revision integer NOT NULL,
313
+ from_node_id text NOT NULL,
314
+ from_kind text NOT NULL,
315
+ to_node_id text NOT NULL,
316
+ to_kind text NOT NULL,
317
+ hour timestamptz NOT NULL,
318
+ reached bigint NOT NULL,
319
+ converted bigint NOT NULL,
320
+ updated_at timestamptz NOT NULL,
321
+ PRIMARY KEY (application_id, audience_id, tree_id, revision, from_node_id, from_kind, to_node_id, to_kind, hour)
322
+ )`,
323
+ /**
324
+ * **One pair of one page over a range**, which is a step's two sides: the
325
+ * primary key cannot serve it, because a step names the tree and the two ends
326
+ * and neither of the columns between them.
327
+ */
328
+ `CREATE INDEX IF NOT EXISTS loom_reader_funnel_hours_pair_idx ON loom_reader_funnel_hours (application_id, tree_id, from_node_id, to_node_id, hour)`,
329
+ /** **Every pair of one application, by hour**, which is the deployment-wide reading. */
330
+ `CREATE INDEX IF NOT EXISTS loom_reader_funnel_hours_hour_idx ON loom_reader_funnel_hours (application_id, hour)`,
331
+ `ALTER TABLE loom_reader_funnel_hours ENABLE ROW LEVEL SECURITY`,
188
332
  ];
189
333
  /** Idempotent, so running it against a populated database is a no-op. */
190
334
  export const ensureReaderSignalsSchema = async (db) => {
@@ -195,15 +195,24 @@ export type SweepNotice = {
195
195
  /** The longest the deployment lets pass between sweeps, as it stated it. */
196
196
  readonly everyMs: number;
197
197
  /**
198
- * The longest a delivery can live: its ripeness window plus one sweep
199
- * interval.
198
+ * The longest a delivery can live: the later of its two windows, plus one
199
+ * sweep interval.
200
200
  *
201
- * The two add because a delivery is not counted until it ripens and then
202
- * not until the next sweep runs, which is the arithmetic
201
+ * A sweep adds because a delivery does not go the instant it is eligible
202
+ * but at the next run, which is the arithmetic
203
203
  * `CollectionSchedule.foldsWithinMs` spells out for the operator's half
204
- * of this question (0274) — so **this is the number to hand the stall
205
- * check**, and a deployment states the interval once rather than keeping
206
- * a reader's ceiling and an operator's threshold in step by hand.
204
+ * of this question (0274) — so **this is the number the retention check
205
+ * is given**, and a deployment states the interval once rather than
206
+ * keeping a reader's ceiling and an operator's threshold in step by hand.
207
+ *
208
+ * **The later of the two windows rather than their sum** (0351). A
209
+ * delivery is counted once it is `bufferMs` old and deleted once it is
210
+ * `keptMs` old, and both are measured from the same instant — the moment
211
+ * it arrived — so the second condition is met at the later of the two
212
+ * ages, not after one window has elapsed and then the other. Where the
213
+ * kept window is the shorter of the two, which is an odd but legal
214
+ * configuration, the delivery still has to be counted before it may go,
215
+ * and the maximum says exactly that.
207
216
  */
208
217
  readonly goneWithinMs: number;
209
218
  }
@@ -222,26 +231,49 @@ export type CollectionNotice = {
222
231
  /** Where readers are counted from, or that they are not. */
223
232
  readonly region: RegionNotice;
224
233
  /**
225
- * How long a delivery itself lives before it is counted and dropped, in
234
+ * How long a delivery waits before it is counted into the totals, in
226
235
  * milliseconds.
227
236
  *
228
- * The deployment's own number (`collect.ts`), and the honest bound on the
229
- * life of the page-view key, since the key exists in the buffer and nowhere
230
- * else. **The framework cannot promise the moment it is swept**, because a
231
- * host schedules the sweep: this is the age at which a delivery becomes ripe,
232
- * not a guarantee about when the next run happens. What the deployment itself
233
- * promises about that is {@link CollectionNotice.sweep}, and
234
- * {@link describeBuffer} says the two together.
237
+ * The deployment's own number (`collect.ts`). **It was the bound on the life
238
+ * of the page-view key and is not any more** (0351): a counted delivery used
239
+ * to be deleted in the same operation, and is now kept for
240
+ * {@link CollectionNotice.keptMs}. **The framework cannot promise the moment
241
+ * either sweep runs**, because a host schedules them: this is the age at
242
+ * which a delivery becomes ripe, not a guarantee about when the next run
243
+ * happens. What the deployment itself promises about that is
244
+ * {@link CollectionNotice.sweep}, and {@link describeBuffer} says all three
245
+ * together.
235
246
  */
236
247
  readonly bufferMs: number;
237
248
  /**
238
- * How often this deployment sweeps a ripe delivery away, where it has stated
239
- * it.
249
+ * How long a delivery itself is kept, measured from when it arrived, in
250
+ * milliseconds.
251
+ *
252
+ * The honest bound on the life of the page-view key, and the number that
253
+ * makes this notice true since 5 November: individual deliveries are kept —
254
+ * thirty days by default — so that a deployment can look at them rather than
255
+ * only at counters (0349), and a notice that went on saying a delivery was
256
+ * deleted an hour after it arrived would be telling every reader of a privacy
257
+ * page something the deployment had stopped doing.
258
+ *
259
+ * Longer than {@link CollectionNotice.bufferMs} on any ordinary
260
+ * configuration, and the ceiling is taken over both rather than off this one,
261
+ * because a delivery is never deleted before it is counted whichever of the
262
+ * two windows is shorter (`expire.ts`).
263
+ */
264
+ readonly keptMs: number;
265
+ /**
266
+ * How often this deployment sweeps, where it has stated it.
240
267
  *
241
268
  * The half of retention that is not the framework's to promise, and the half
242
- * a reader of `bufferMs` alone would assume. {@link describeBuffer} takes the
243
- * two together for that reason: an age with no sweep beside it is a sentence
244
- * that reads like a deletion and is not one.
269
+ * a reader of the two windows alone would assume. {@link describeBuffer}
270
+ * takes them together for that reason: an age with no sweep beside it is a
271
+ * sentence that reads like a deletion and is not one.
272
+ *
273
+ * **One stated interval covers both sweeps**, because a deployment runs them
274
+ * from one place — counting and then expiring, in that order, in one cron
275
+ * route (0351). A deployment that ran them on two schedules would be stating
276
+ * the longer of the two here, which is what the ceiling needs.
245
277
  */
246
278
  readonly sweep: SweepNotice;
247
279
  };
@@ -254,23 +286,31 @@ export type CollectedKind = {
254
286
  readonly carries: readonly CollectedField[];
255
287
  };
256
288
  /**
257
- * Both halves of how long a delivery lives: the age it ripens at, and how often
258
- * the deployment takes the ripe ones away.
289
+ * Every part of how long a delivery lives: the age it is counted at, the age it
290
+ * is deleted at, and how often the deployment's sweep runs.
259
291
  *
260
- * A `Pick` of the notice rather than two arguments, so that the sentence cannot
261
- * be built from one of them. The age alone reads as a deletion and is not one.
292
+ * A `Pick` of the notice rather than three arguments, so that the sentence
293
+ * cannot be built from some of them. The ripeness age alone reads as a deletion
294
+ * and is not one — and since 5 November it is not even the deletion's age
295
+ * (0351).
262
296
  */
263
- export type DeliveryRetention = Pick<CollectionNotice, "bufferMs" | "sweep">;
297
+ export type DeliveryRetention = Pick<CollectionNotice, "bufferMs" | "keptMs" | "sweep">;
264
298
  /**
265
299
  * How long a delivery lives, addressed to the reader.
266
300
  *
267
- * It takes the retention whole, because the age is the half the framework knows
268
- * and the sweep is the half it cannot promise, and a notice that published the
269
- * first without the second said *a delivery is kept until it is 60 minutes old*
270
- * to a reader who had no way of hearing *…or for ever, if nobody runs the
271
- * sweep*. Where a schedule was stated the sentence ends on a ceiling a reader
272
- * can hold the deployment to; where none was, it says that in as many words
273
- * rather than leaving the age to be read as a promise.
301
+ * It takes the retention whole, because the two ages are the halves the
302
+ * framework knows and the sweep is the half it cannot promise, and a notice
303
+ * that published an age without the sweep said *a delivery is kept until it is
304
+ * 60 minutes old* to a reader who had no way of hearing *…or for ever, if
305
+ * nobody runs the sweep*. Where a schedule was stated the sentence ends on a
306
+ * ceiling a reader can hold the deployment to; where none was, it says that in
307
+ * as many words rather than leaving the ages to be read as a promise.
308
+ *
309
+ * **Two ages since 5 November, and saying one of them would be the lie** (0349,
310
+ * 0351). A delivery is counted at the first age and deleted at the second, and
311
+ * the sentence is explicit about what the gap is for: so that the deployment
312
+ * can look at the deliveries behind its totals. A reader told only *counted
313
+ * into totals* would reasonably assume the delivery was gone.
274
314
  */
275
315
  export declare const describeBuffer: (retention: DeliveryRetention) => string;
276
316
  /** The configuration a notice is of. */
@@ -301,7 +341,7 @@ export type NoticeRequest = {
301
341
  * minimum is raised to it, by the same helper the region map itself uses.
302
342
  */
303
343
  readonly region?: {
304
- readonly floor?: number;
344
+ readonly floor?: number | undefined;
305
345
  };
306
346
  /**
307
347
  * How often this deployment's sweep runs, where it has stated it.
@@ -317,6 +357,21 @@ export type NoticeRequest = {
317
357
  readonly sweep?: {
318
358
  readonly everyMs: number;
319
359
  };
360
+ /**
361
+ * The window this deployment keeps individual deliveries for, from its own
362
+ * `ExpiryRequest` (`expire.ts`). The default when absent.
363
+ *
364
+ * Reported as given rather than clamped, as the collection window is and for
365
+ * the same reason: `expire.ts` is what refuses a window below its minimum.
366
+ *
367
+ * **Absent is the default rather than *nothing is kept*,** which is the one
368
+ * place this field differs in spirit from the sweep beside it. A deployment
369
+ * that calls the expiry sweep with no window gets thirty days (0349), so a
370
+ * notice that read an absent setting as *deleted the moment it is counted*
371
+ * would understate what is kept — and this module's standing rule is that it
372
+ * may overstate what is collected and may never overstate what is deleted.
373
+ */
374
+ readonly keptMs?: number;
320
375
  };
321
376
  /**
322
377
  * What a page broadcast with these options reports, as a deployment may publish
@@ -1,5 +1,6 @@
1
1
  import { everyMemberOf } from "../closed-set.js";
2
2
  import { DEFAULT_READER_SIGNAL_WINDOW_MS } from "./collect.js";
3
+ import { DEFAULT_READER_EVENT_RETENTION_MS } from "./expire.js";
3
4
  import { regionFloorOf } from "./region.js";
4
5
  import { READER_SIGNAL_KINDS, } from "./signal.js";
5
6
  /**
@@ -150,35 +151,54 @@ const OBSERVES = {
150
151
  * A length of time as a notice says it.
151
152
  *
152
153
  * Minutes above a minute and seconds below it, because the one number here a
153
- * deployment can set low is the buffer and `collect.ts` floors it at a minute
154
+ * deployment could set low is the buffer and `collect.ts` floors it at a minute
154
155
  * — so a notice reading *0 minutes* would be reporting a window the collector
155
156
  * would refuse to run on.
157
+ *
158
+ * **Days above a day**, which the kept window asked for (0351): thirty days is
159
+ * the default a deployment keeps individual deliveries for, and *43200 minutes*
160
+ * is a number no reader of a privacy page can hold. The break is at a day
161
+ * rather than at an hour so that every figure a notice published before the
162
+ * kept window existed still reads exactly as it did — an hour is *60 minutes*
163
+ * here, as it has been, and the one new figure is the one that needed a bigger
164
+ * unit.
156
165
  */
157
166
  const inWords = (ms) => {
158
167
  if (ms < 60_000) {
159
168
  const seconds = Math.round(ms / 1000);
160
169
  return seconds === 1 ? "a second" : `${seconds} seconds`;
161
170
  }
162
- const minutes = Math.round(ms / 60_000);
163
- return minutes === 1 ? "a minute" : `${minutes} minutes`;
171
+ if (ms < 24 * 60 * 60_000) {
172
+ const minutes = Math.round(ms / 60_000);
173
+ return minutes === 1 ? "a minute" : `${minutes} minutes`;
174
+ }
175
+ const days = Math.round(ms / (24 * 60 * 60_000));
176
+ return days === 1 ? "a day" : `${days} days`;
164
177
  };
165
178
  /**
166
179
  * How long a delivery lives, addressed to the reader.
167
180
  *
168
- * It takes the retention whole, because the age is the half the framework knows
169
- * and the sweep is the half it cannot promise, and a notice that published the
170
- * first without the second said *a delivery is kept until it is 60 minutes old*
171
- * to a reader who had no way of hearing *…or for ever, if nobody runs the
172
- * sweep*. Where a schedule was stated the sentence ends on a ceiling a reader
173
- * can hold the deployment to; where none was, it says that in as many words
174
- * rather than leaving the age to be read as a promise.
181
+ * It takes the retention whole, because the two ages are the halves the
182
+ * framework knows and the sweep is the half it cannot promise, and a notice
183
+ * that published an age without the sweep said *a delivery is kept until it is
184
+ * 60 minutes old* to a reader who had no way of hearing *…or for ever, if
185
+ * nobody runs the sweep*. Where a schedule was stated the sentence ends on a
186
+ * ceiling a reader can hold the deployment to; where none was, it says that in
187
+ * as many words rather than leaving the ages to be read as a promise.
188
+ *
189
+ * **Two ages since 5 November, and saying one of them would be the lie** (0349,
190
+ * 0351). A delivery is counted at the first age and deleted at the second, and
191
+ * the sentence is explicit about what the gap is for: so that the deployment
192
+ * can look at the deliveries behind its totals. A reader told only *counted
193
+ * into totals* would reasonably assume the delivery was gone.
175
194
  */
176
195
  export const describeBuffer = (retention) => {
177
- const ripens = `a delivery is kept until it is ${inWords(retention.bufferMs)} old, and this deployment's own sweep is what then counts it into totals and deletes it`;
196
+ const counts = `a delivery is counted into this deployment's totals once it is ${inWords(retention.bufferMs)} old`;
197
+ const kept = `it is then kept for ${inWords(retention.keptMs)} from when it arrived, so that this deployment can look at the deliveries its totals were made from, and its own sweep is what deletes it`;
178
198
  const totals = "the totals it leaves behind have nobody in them, and they are kept";
179
199
  return retention.sweep.state === "stated"
180
- ? `${ripens}; that sweep runs at least every ${inWords(retention.sweep.everyMs)}, so a delivery is gone within ${inWords(retention.sweep.goneWithinMs)} of arriving — the key tying one visit together exists until then and nowhere else; ${totals}`
181
- : `${ripens}; this deployment has not said how often that sweep runs, so nothing here promises when a ripe delivery actually goes — the key tying one visit together exists until the sweep takes it and nowhere else; ${totals}`;
200
+ ? `${counts}; ${kept}; that sweep runs at least every ${inWords(retention.sweep.everyMs)}, so a delivery is gone within ${inWords(retention.sweep.goneWithinMs)} of arriving — the key tying one visit together exists until then and nowhere else; ${totals}`
201
+ : `${counts}; ${kept}; this deployment has not said how often that sweep runs, so nothing here promises when a kept delivery actually goes — the key tying one visit together exists until the sweep takes it and nowhere else; ${totals}`;
182
202
  };
183
203
  /**
184
204
  * What a stated interval becomes on a notice.
@@ -194,9 +214,9 @@ export const describeBuffer = (retention) => {
194
214
  * standing rule is that it may overstate what is collected and may never
195
215
  * overstate what is deleted.
196
216
  */
197
- const sweepNoticeOf = (everyMs, bufferMs) => everyMs === undefined || !Number.isFinite(everyMs) || everyMs <= 0
217
+ const sweepNoticeOf = (everyMs, bufferMs, keptMs) => everyMs === undefined || !Number.isFinite(everyMs) || everyMs <= 0
198
218
  ? { state: "unstated" }
199
- : { state: "stated", everyMs, goneWithinMs: bufferMs + everyMs };
219
+ : { state: "stated", everyMs, goneWithinMs: Math.max(bufferMs, keptMs) + everyMs };
200
220
  /**
201
221
  * What a page broadcast with these options reports, as a deployment may publish
202
222
  * it.
@@ -211,6 +231,7 @@ const sweepNoticeOf = (everyMs, bufferMs) => everyMs === undefined || !Number.is
211
231
  export const collectionNoticeOf = (request = {}) => {
212
232
  const asked = request.page?.kinds;
213
233
  const bufferMs = request.windowMs ?? DEFAULT_READER_SIGNAL_WINDOW_MS;
234
+ const keptMs = request.keptMs ?? DEFAULT_READER_EVENT_RETENTION_MS;
214
235
  const collects = READER_SIGNAL_KINDS.filter((kind) => asked === undefined || asked.includes(kind)).map((kind) => ({
215
236
  kind,
216
237
  observes: OBSERVES[kind],
@@ -222,7 +243,8 @@ export const collectionNoticeOf = (request = {}) => {
222
243
  refuses: REFUSALS,
223
244
  region: { floor: request.region === undefined ? null : regionFloorOf(request.region.floor) },
224
245
  bufferMs,
225
- sweep: sweepNoticeOf(request.sweep?.everyMs, bufferMs),
246
+ keptMs,
247
+ sweep: sweepNoticeOf(request.sweep?.everyMs, bufferMs, keptMs),
226
248
  };
227
249
  };
228
250
  //# sourceMappingURL=notice.js.map