@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,6 +1,6 @@
1
1
  import type { LoomDatabase } from "../store/database.js";
2
2
  /**
3
- * Creating the three reader-signal tables, with row level security switched on.
3
+ * Creating the five 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
@@ -12,9 +12,24 @@ import type { LoomDatabase } from "../store/database.js";
12
12
  * is the only combination in Loom that could correlate anything across a
13
13
  * tenancy boundary. It expires within hours; the policy does not depend on
14
14
  * that.
15
+ *
16
+ * 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
+ * there is no earlier spelling to correct the way `APPLICATION_ID_MIGRATION`
19
+ * corrects the store's — rows that predate the column belong to the deployment
20
+ * that wrote them, which is what `app_default` names.
21
+ *
22
+ * Every table then carries `audience_id`, the second migration 0273 owed and
23
+ * [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
24
+ * settles. Backfilled by its default for the stronger version of the same
25
+ * reason: a row written before the dimension existed was collected when there
26
+ * was one form of every page, so `aud_everyone` is what was true of it rather
27
+ * than a value somebody picked. The four counters take it into their keys; the
28
+ * buffer takes the column and keeps its key and its index, because nothing
29
+ * reads the buffer by audience.
15
30
  */
16
31
  /**
17
- * The three tables, as statements a host can run.
32
+ * The five tables, as statements a host can run.
18
33
  *
19
34
  * One statement per entry for the same reason the store's DDL is a list: a
20
35
  * 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 three reader-signal tables, with row level security switched on.
3
+ * Creating the five 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
@@ -12,9 +12,24 @@ import { sql } from "drizzle-orm";
12
12
  * is the only combination in Loom that could correlate anything across a
13
13
  * tenancy boundary. It expires within hours; the policy does not depend on
14
14
  * that.
15
+ *
16
+ * 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
+ * there is no earlier spelling to correct the way `APPLICATION_ID_MIGRATION`
19
+ * corrects the store's — rows that predate the column belong to the deployment
20
+ * that wrote them, which is what `app_default` names.
21
+ *
22
+ * Every table then carries `audience_id`, the second migration 0273 owed and
23
+ * [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
24
+ * settles. Backfilled by its default for the stronger version of the same
25
+ * reason: a row written before the dimension existed was collected when there
26
+ * was one form of every page, so `aud_everyone` is what was true of it rather
27
+ * than a value somebody picked. The four counters take it into their keys; the
28
+ * buffer takes the column and keeps its key and its index, because nothing
29
+ * reads the buffer by audience.
15
30
  */
16
31
  /**
17
- * The three tables, as statements a host can run.
32
+ * The five tables, as statements a host can run.
18
33
  *
19
34
  * One statement per entry for the same reason the store's DDL is a list: a
20
35
  * driver may refuse several commands in a single prepared statement, and
@@ -23,6 +38,8 @@ import { sql } from "drizzle-orm";
23
38
  */
24
39
  export const READER_SIGNALS_DDL = [
25
40
  `CREATE TABLE IF NOT EXISTS loom_reader_signals (
41
+ application_id text NOT NULL DEFAULT 'app_default',
42
+ audience_id text NOT NULL DEFAULT 'aud_everyone',
26
43
  seq bigserial PRIMARY KEY,
27
44
  tree_id text NOT NULL,
28
45
  revision integer NOT NULL,
@@ -31,9 +48,41 @@ export const READER_SIGNALS_DDL = [
31
48
  signals jsonb NOT NULL,
32
49
  received_at timestamptz NOT NULL DEFAULT now()
33
50
  )`,
34
- `CREATE INDEX IF NOT EXISTS loom_reader_signals_tree_seq_idx ON loom_reader_signals (tree_id, seq)`,
51
+ /**
52
+ * **The application, for a database that predates it (0269).** The same
53
+ * shape the store's tables take: the column is additive and defaulted, and
54
+ * then the index is rebuilt to lead with it.
55
+ *
56
+ * The buffer's key does not widen, unlike the four counters below. It is
57
+ * `seq`, a `bigserial`, which is already unique across every application the
58
+ * database holds — so leading the key with the application would be a wider
59
+ * key for no constraint that was not already enforced. The index is the part
60
+ * that matters here, because the index is what the reads use.
61
+ *
62
+ * Dropped by name rather than created `IF NOT EXISTS`, for the reason the
63
+ * store's note gives: the name does not change, so an existing index on the
64
+ * old columns would be left exactly as it was and every read would go on
65
+ * scanning across applications while appearing to be indexed.
66
+ */
67
+ `ALTER TABLE loom_reader_signals ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
68
+ /**
69
+ * **The audience, for a database that predates it (0284).** Additive and
70
+ * defaulted, and here the index is *not* rebuilt around it — the one place
71
+ * this dimension departs from the shape the application took.
72
+ *
73
+ * Every read of the buffer filters the application, optionally the tree, and
74
+ * the sequence; none of them filters the audience, because a rollup folds a
75
+ * whole window and groups by the column afterwards. Leading the index with it
76
+ * would push `tree_id` and `seq` out of the prefix and widen every scan that
77
+ * exists to serve a filter nothing expresses.
78
+ */
79
+ `ALTER TABLE loom_reader_signals ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
80
+ `DROP INDEX IF EXISTS loom_reader_signals_tree_seq_idx`,
81
+ `CREATE INDEX IF NOT EXISTS loom_reader_signals_tree_seq_idx ON loom_reader_signals (application_id, tree_id, seq)`,
35
82
  `ALTER TABLE loom_reader_signals ENABLE ROW LEVEL SECURITY`,
36
83
  `CREATE TABLE IF NOT EXISTS loom_reader_tallies (
84
+ application_id text NOT NULL DEFAULT 'app_default',
85
+ audience_id text NOT NULL DEFAULT 'aud_everyone',
37
86
  tree_id text NOT NULL,
38
87
  revision integer NOT NULL,
39
88
  node_id text NOT NULL,
@@ -45,8 +94,9 @@ export const READER_SIGNALS_DDL = [
45
94
  activations bigint NOT NULL,
46
95
  opens bigint NOT NULL,
47
96
  closes bigint NOT NULL,
97
+ completions bigint NOT NULL DEFAULT 0,
48
98
  updated_at timestamptz NOT NULL,
49
- PRIMARY KEY (tree_id, revision, node_id)
99
+ PRIMARY KEY (application_id, audience_id, tree_id, revision, node_id)
50
100
  )`,
51
101
  /**
52
102
  * For a deployment whose tallies table predates the counter regions are
@@ -54,8 +104,22 @@ export const READER_SIGNALS_DDL = [
54
104
  * measured doing anything in here*, which is what was true of them.
55
105
  */
56
106
  `ALTER TABLE loom_reader_tallies ADD COLUMN IF NOT EXISTS engaged bigint NOT NULL DEFAULT 0`,
107
+ /**
108
+ * For a deployment whose tallies table predates the fifth kind. Additive and
109
+ * defaulted, so existing rows read as *nothing was submitted here*, which is
110
+ * what nobody was counting.
111
+ */
112
+ `ALTER TABLE loom_reader_tallies ADD COLUMN IF NOT EXISTS completions bigint NOT NULL DEFAULT 0`,
113
+ /** The application, for a database that predates it — see the buffer's note above. */
114
+ `ALTER TABLE loom_reader_tallies ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
115
+ /** The audience, for a database that predates it — see the buffer's note above. */
116
+ `ALTER TABLE loom_reader_tallies ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
117
+ `ALTER TABLE loom_reader_tallies DROP CONSTRAINT IF EXISTS loom_reader_tallies_pkey`,
118
+ `ALTER TABLE loom_reader_tallies ADD PRIMARY KEY (application_id, audience_id, tree_id, revision, node_id)`,
57
119
  `ALTER TABLE loom_reader_tallies ENABLE ROW LEVEL SECURITY`,
58
120
  `CREATE TABLE IF NOT EXISTS loom_reader_funnels (
121
+ application_id text NOT NULL DEFAULT 'app_default',
122
+ audience_id text NOT NULL DEFAULT 'aud_everyone',
59
123
  tree_id text NOT NULL,
60
124
  revision integer NOT NULL,
61
125
  from_node_id text NOT NULL,
@@ -65,9 +129,62 @@ export const READER_SIGNALS_DDL = [
65
129
  reached bigint NOT NULL,
66
130
  converted bigint NOT NULL,
67
131
  updated_at timestamptz NOT NULL,
68
- PRIMARY KEY (tree_id, revision, from_node_id, from_kind, to_node_id, to_kind)
132
+ PRIMARY KEY (application_id, audience_id, tree_id, revision, from_node_id, from_kind, to_node_id, to_kind)
69
133
  )`,
134
+ /** The application, for a database that predates it — see the buffer's note above. */
135
+ `ALTER TABLE loom_reader_funnels ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
136
+ /** The audience, for a database that predates it — see the buffer's note above. */
137
+ `ALTER TABLE loom_reader_funnels ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
138
+ `ALTER TABLE loom_reader_funnels DROP CONSTRAINT IF EXISTS loom_reader_funnels_pkey`,
139
+ `ALTER TABLE loom_reader_funnels ADD PRIMARY KEY (application_id, audience_id, tree_id, revision, from_node_id, from_kind, to_node_id, to_kind)`,
70
140
  `ALTER TABLE loom_reader_funnels ENABLE ROW LEVEL SECURITY`,
141
+ `CREATE TABLE IF NOT EXISTS loom_reader_regions (
142
+ application_id text NOT NULL DEFAULT 'app_default',
143
+ audience_id text NOT NULL DEFAULT 'aud_everyone',
144
+ tree_id text NOT NULL,
145
+ revision integer NOT NULL,
146
+ region text NOT NULL,
147
+ views bigint NOT NULL,
148
+ updated_at timestamptz NOT NULL,
149
+ PRIMARY KEY (application_id, audience_id, tree_id, revision, region)
150
+ )`,
151
+ /** The application, for a database that predates it — see the buffer's note above. */
152
+ `ALTER TABLE loom_reader_regions ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
153
+ /** The audience, for a database that predates it — see the buffer's note above. */
154
+ `ALTER TABLE loom_reader_regions ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
155
+ `ALTER TABLE loom_reader_regions DROP CONSTRAINT IF EXISTS loom_reader_regions_pkey`,
156
+ `ALTER TABLE loom_reader_regions ADD PRIMARY KEY (application_id, audience_id, tree_id, revision, region)`,
157
+ `ALTER TABLE loom_reader_regions ENABLE ROW LEVEL SECURITY`,
158
+ `CREATE TABLE IF NOT EXISTS loom_reader_page_views (
159
+ application_id text NOT NULL DEFAULT 'app_default',
160
+ audience_id text NOT NULL DEFAULT 'aud_everyone',
161
+ tree_id text NOT NULL,
162
+ revision integer NOT NULL,
163
+ opened bigint NOT NULL DEFAULT 0,
164
+ appearances bigint NOT NULL DEFAULT 0,
165
+ updated_at timestamptz NOT NULL,
166
+ folded_at timestamptz,
167
+ PRIMARY KEY (application_id, audience_id, tree_id, revision)
168
+ )`,
169
+ /**
170
+ * **When the fold last touched the row**, for a deployment whose page-view
171
+ * table predates the question.
172
+ *
173
+ * Additive, nullable and undefaulted, which is the only honest value: no
174
+ * backfill exists, because nothing wrote down when those rows were folded
175
+ * and `updated_at` cannot be read as it — it is written by the door as well.
176
+ * An existing row therefore reads *nothing attests a fold*, which is a state
177
+ * the reading publishes and raises no fault from, and the first fold after
178
+ * the migration fills it in.
179
+ */
180
+ `ALTER TABLE loom_reader_page_views ADD COLUMN IF NOT EXISTS folded_at timestamptz`,
181
+ /** The application, for a database that predates it — see the buffer's note above. */
182
+ `ALTER TABLE loom_reader_page_views ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
183
+ /** The audience, for a database that predates it — see the buffer's note above. */
184
+ `ALTER TABLE loom_reader_page_views ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
185
+ `ALTER TABLE loom_reader_page_views DROP CONSTRAINT IF EXISTS loom_reader_page_views_pkey`,
186
+ `ALTER TABLE loom_reader_page_views ADD PRIMARY KEY (application_id, audience_id, tree_id, revision)`,
187
+ `ALTER TABLE loom_reader_page_views ENABLE ROW LEVEL SECURITY`,
71
188
  ];
72
189
  /** Idempotent, so running it against a populated database is a no-op. */
73
190
  export const ensureReaderSignalsSchema = async (db) => {
@@ -0,0 +1,334 @@
1
+ import type { ReaderSignalOptions } from "./broadcast.js";
2
+ import { type ReaderSignal, type ReaderSignalBatch, type ReaderSignalKind } from "./signal.js";
3
+ /**
4
+ * What a published page reports, written for the people it reports about.
5
+ *
6
+ * Every other reading in this subsystem answers a deployment's question. This
7
+ * is the one that answers a reader's, and it is the half of the argument that
8
+ * had nothing behind it: Loom exists so that a change to a page can be
9
+ * inspected, attributed and undone, and reader measurement that could not be
10
+ * explained to the person being measured would contradict the whole premise.
11
+ * Every competitor in this space collects more and explains less; the
12
+ * explaining has to be something a deployment can publish, not a paragraph in
13
+ * this repository.
14
+ *
15
+ * So this is a value rather than a page: a structure a deployment's privacy
16
+ * page, portal or consent surface can print, derived from the configuration its
17
+ * own pages are broadcast with.
18
+ *
19
+ * ## Why it is derived and not written
20
+ *
21
+ * A hand-written list of what a product collects is right on the day it is
22
+ * written. This one cannot drift from the payload, and it is the type system
23
+ * that holds it rather than a reviewer: {@link DELIVERY_FIELDS} and
24
+ * {@link SIGNAL_FIELDS} are keyed by the schema's own fields through
25
+ * `keyof Required<…>`, so **a field added to a batch without a sentence here
26
+ * does not compile.** `notice.test.ts` holds the other end, which a type cannot
27
+ * reach: it drives the real broadcaster over a real page and fails if a kind or
28
+ * a field arrives that this does not name.
29
+ *
30
+ * ## It is a ceiling, and never an understatement
31
+ *
32
+ * The notice names everything the configuration permits. A deployment that
33
+ * narrows `types` collects about fewer parts than this says, and one that turns
34
+ * `within` off carries no ancestry on the three delegated kinds. Both are
35
+ * published here as though they were on.
36
+ *
37
+ * That is deliberate in one direction only. A disclosure that overstates costs
38
+ * a reader nothing and a deployment a little credit; one that understates is
39
+ * the failure this module exists to make impossible. It also keeps the notice
40
+ * stable: a ceiling changes when the vocabulary or the deployment's own three
41
+ * numbers change, where a floor would have to be republished every time
42
+ * somebody added a primitive type to a list.
43
+ *
44
+ * ## What it is not
45
+ *
46
+ * **Not a consent gate and not a banner.** There is nothing here to consent to:
47
+ * a signal is anonymous and node-shaped, correlation is scoped to one page view
48
+ * by a key that never persists, and neither is configurable
49
+ * ([0146](../../decisions/0146-a-reader-signal-stays-anonymous-and-a-funnel-is-correlated-inside-one-page-view.md)).
50
+ * A notice says what is collected; the rules say it cannot be about a person.
51
+ * Per-reader identity is parked, and nothing here assumes it ever arrives or
52
+ * builds toward it — what a gate would need is a recorded decision, which is a
53
+ * different artefact from this one.
54
+ *
55
+ * **Not a reading.** It touches no store, no clock and no counter. Three
56
+ * numbers come from the deployment's own configuration — the window a
57
+ * delivery ripens at, the floor under a published country, and how often its
58
+ * sweep runs (0320) — and everything else is the vocabulary.
59
+ *
60
+ * ## The voice
61
+ *
62
+ * Every sentence in this module is addressed to a reader of the page, because
63
+ * that is who ends up reading them: *your address is never stored*, not *the
64
+ * reader's address is never stored*. It is the one module in `src/signals/`
65
+ * that speaks to anybody.
66
+ */
67
+ /** What one field of a delivery is about. */
68
+ export type FieldSubject =
69
+ /** The part of the page the observation is about. */
70
+ "part"
71
+ /** Which page, which revision of it, and which form was served. */
72
+ | "page"
73
+ /** What was observed about the part — when, how long, open or closed. */
74
+ | "observation"
75
+ /**
76
+ * The one visit the delivery belongs to.
77
+ *
78
+ * The narrowest scope anything here is correlated at, and the only one about
79
+ * a visit rather than about a page (0146).
80
+ */
81
+ | "page-view"
82
+ /** The delivery itself — when it was sent, and what it carried. */
83
+ | "delivery";
84
+ /**
85
+ * The closed set, for a surface grouping a notice by what its fields are about.
86
+ *
87
+ * **There is deliberately no member for the reader.** Every field of every
88
+ * batch is about one of these five things, which is rule 1 stated as a type
89
+ * rather than as a sentence: a field that needed a sixth member would be a
90
+ * field about a person, and adding one is a decision record and not a
91
+ * judgement call inside a pull request.
92
+ */
93
+ export declare const FIELD_SUBJECTS: readonly FieldSubject[];
94
+ /** One line per subject, addressed to the reader, for a surface grouping a notice. */
95
+ export declare const describeFieldSubject: (subject: FieldSubject) => string;
96
+ /** One field of a payload, and what it says. */
97
+ export type CollectedField = {
98
+ /** The field's name in the delivery, which is what a reader comparing this to a payload sees. */
99
+ readonly field: string;
100
+ /** What it is about. */
101
+ readonly subject: FieldSubject;
102
+ /** One sentence, addressed to the reader. */
103
+ readonly says: string;
104
+ };
105
+ /** A field as the tables below hold it, before its name is read off the key. */
106
+ type FieldNote = Omit<CollectedField, "field">;
107
+ /**
108
+ * Every field of one shape, keyed by the shape's own fields.
109
+ *
110
+ * `Required` is what makes an optional field — `within`, `view`, `audience`,
111
+ * `first` — as mandatory to describe as any other. A reader is owed a sentence
112
+ * about a field that is sometimes there.
113
+ */
114
+ type FieldsOf<Shape> = {
115
+ readonly [Field in keyof Required<Shape>]: FieldNote;
116
+ };
117
+ /**
118
+ * Every kind's fields.
119
+ *
120
+ * Spread from {@link ADDRESS_FIELDS} rather than written five times, with the
121
+ * per-kind annotation doing the checking: the three shared entries plus
122
+ * whatever that kind adds has to be exactly the fields the schema gives it.
123
+ */
124
+ export declare const SIGNAL_FIELDS: {
125
+ readonly [Kind in ReaderSignalKind]: FieldsOf<Extract<ReaderSignal, {
126
+ kind: Kind;
127
+ }>>;
128
+ };
129
+ /** What travels with a delivery, whatever observations are in it. */
130
+ export declare const DELIVERY_FIELDS: FieldsOf<ReaderSignalBatch>;
131
+ /** Something a reader signal never carries, whatever a deployment configures. */
132
+ export type Refusal =
133
+ /**
134
+ * No identifier for a person or a device, and nothing standing in for one.
135
+ *
136
+ * The first clause of rule 1. The second half of the sentence is the half
137
+ * that matters to somebody who has read a privacy policy before: an
138
+ * identifier nobody set is still an identifier.
139
+ */
140
+ "no-identifier"
141
+ /** No signature derived from a device, a browser or its settings. */
142
+ | "no-fingerprint"
143
+ /** Nothing the page said to you and nothing you said to it. */
144
+ | "no-content"
145
+ /** No cursor, no scroll trace, no recording. */
146
+ | "no-pointer-path"
147
+ /** Nothing that joins one visit to another. */
148
+ | "no-stitching"
149
+ /** Nothing derived from your address outlives the request it arrived on. */
150
+ | "no-address";
151
+ /** The closed set, for a surface listing what is refused. */
152
+ export declare const REFUSALS: readonly Refusal[];
153
+ /** One line per refusal, addressed to the reader. */
154
+ export declare const describeRefusal: (refusal: Refusal) => string;
155
+ /** Where a deployment counts its readers from, or that it does not. */
156
+ export type RegionNotice = {
157
+ /**
158
+ * The page views a country needs before it is published at all, or `null`
159
+ * where no country is read.
160
+ *
161
+ * `null` is *nothing about where you are is read*, which is a different
162
+ * sentence from *your country is counted and will not be published until
163
+ * enough others share it* — and the difference is the whole of what a floor
164
+ * is for. A country with a handful of views in it is a person (§7).
165
+ */
166
+ readonly floor: number | null;
167
+ };
168
+ /** One or two sentences about where readers are counted from, addressed to the reader. */
169
+ export declare const describeRegionNotice: (notice: RegionNotice) => string;
170
+ /**
171
+ * How often the deployment's own sweep runs, or that it has not said.
172
+ *
173
+ * The one thing a reader of {@link CollectionNotice.bufferMs} could not find
174
+ * out. `bufferMs` is the age at which a delivery becomes *ripe* — ready to be
175
+ * counted into the totals and deleted — and nothing in `src/signals/` deletes
176
+ * it: a host calls {@link collectReaderSignals} from a cron, a deploy hook or
177
+ * by hand (0146, 0158). So a deployment that never scheduled the sweep keeps
178
+ * every delivery for ever while its notice names an hour, and *a delivery is
179
+ * kept until it is 60 minutes old* was read by somebody with no way of hearing
180
+ * *…or indefinitely*.
181
+ *
182
+ * The deployment is the only party that knows how often it sweeps, so it states
183
+ * it — the shape `CollectionSchedule` already takes for the operator's half of
184
+ * the same fact
185
+ * ([0274](../../decisions/0274-a-page-view-row-says-when-the-fold-last-touched-it-and-a-stall-is-judged-against-a-schedule-the-deployment-hands-in.md)).
186
+ * A framework that guessed an interval would publish a ceiling nobody promised.
187
+ *
188
+ * **Two states rather than a nullable number**, because the ceiling has to be
189
+ * unreachable where no schedule was stated: a surface cannot print *gone within
190
+ * 70 minutes* on a deployment that promised nothing, which is the one way this
191
+ * field could make a notice overstate.
192
+ */
193
+ export type SweepNotice = {
194
+ readonly state: "stated";
195
+ /** The longest the deployment lets pass between sweeps, as it stated it. */
196
+ readonly everyMs: number;
197
+ /**
198
+ * The longest a delivery can live: its ripeness window plus one sweep
199
+ * interval.
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
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.
207
+ */
208
+ readonly goneWithinMs: number;
209
+ }
210
+ /** Nothing was stated, so nothing here says when a ripe delivery actually goes. */
211
+ | {
212
+ readonly state: "unstated";
213
+ };
214
+ /** What a published page reports, and what it refuses to. */
215
+ export type CollectionNotice = {
216
+ /** The kinds this configuration broadcasts, in the vocabulary's order. */
217
+ readonly collects: readonly CollectedKind[];
218
+ /** What travels with every delivery. */
219
+ readonly delivery: readonly CollectedField[];
220
+ /** What is never collected, whatever else is configured. */
221
+ readonly refuses: readonly Refusal[];
222
+ /** Where readers are counted from, or that they are not. */
223
+ readonly region: RegionNotice;
224
+ /**
225
+ * How long a delivery itself lives before it is counted and dropped, in
226
+ * milliseconds.
227
+ *
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.
235
+ */
236
+ readonly bufferMs: number;
237
+ /**
238
+ * How often this deployment sweeps a ripe delivery away, where it has stated
239
+ * it.
240
+ *
241
+ * 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.
245
+ */
246
+ readonly sweep: SweepNotice;
247
+ };
248
+ /** One kind of observation, with the fields it carries. */
249
+ export type CollectedKind = {
250
+ readonly kind: ReaderSignalKind;
251
+ /** What the page observed, addressed to the reader. */
252
+ readonly observes: string;
253
+ /** Every field that kind carries, including the ones it sometimes omits. */
254
+ readonly carries: readonly CollectedField[];
255
+ };
256
+ /**
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.
259
+ *
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.
262
+ */
263
+ export type DeliveryRetention = Pick<CollectionNotice, "bufferMs" | "sweep">;
264
+ /**
265
+ * How long a delivery lives, addressed to the reader.
266
+ *
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.
274
+ */
275
+ export declare const describeBuffer: (retention: DeliveryRetention) => string;
276
+ /** The configuration a notice is of. */
277
+ export type NoticeRequest = {
278
+ /**
279
+ * The options the page is broadcast with — the same object, so that a notice
280
+ * and the page it is about cannot disagree about which kinds are reported.
281
+ *
282
+ * Only `kinds` is read. `types` and `within` narrow collection below what the
283
+ * notice says, which is the ceiling rule above.
284
+ */
285
+ readonly page?: Pick<ReaderSignalOptions, "kinds">;
286
+ /**
287
+ * The window the deployment collects on, from its own `CollectionRequest`
288
+ * (`collect.ts`). The default when absent.
289
+ *
290
+ * Reported as given rather than clamped: `collect.ts` is what refuses a
291
+ * window below its minimum, and a notice that silently reported a different
292
+ * number from the one a deployment configured would be a second rule about
293
+ * one setting.
294
+ */
295
+ readonly windowMs?: number;
296
+ /**
297
+ * The region counting this deployment's intake does, where it does any.
298
+ *
299
+ * Absent is *no country is read*, which is the default: reading one is
300
+ * something an intake is configured to do (§7). A floor below the published
301
+ * minimum is raised to it, by the same helper the region map itself uses.
302
+ */
303
+ readonly region?: {
304
+ readonly floor?: number;
305
+ };
306
+ /**
307
+ * How often this deployment's sweep runs, where it has stated it.
308
+ *
309
+ * Absent is *nothing is stated*, which is the honest default: nothing in this
310
+ * subsystem schedules a sweep, so a notice that assumed one would publish a
311
+ * ceiling no deployment promised. A value that is not a positive, finite
312
+ * number of milliseconds is read the same way — the notice may always
313
+ * promise a reader less than the deployment knows and may never promise more,
314
+ * and the operator-facing half, where a value that could not be read is said
315
+ * out loud, is a deployment's own settings (0317).
316
+ */
317
+ readonly sweep?: {
318
+ readonly everyMs: number;
319
+ };
320
+ };
321
+ /**
322
+ * What a page broadcast with these options reports, as a deployment may publish
323
+ * it.
324
+ *
325
+ * Pure, and allocation-per-call: no store, no clock, no DOM.
326
+ *
327
+ * The kinds come out in the vocabulary's order and each appears once, whatever
328
+ * order a configuration names them in and however often — a notice is read by
329
+ * somebody who did not write the configuration, and *dwelled, dwelled, viewed*
330
+ * is a leak of how the options were typed rather than a fact about the page.
331
+ */
332
+ export declare const collectionNoticeOf: (request?: NoticeRequest) => CollectionNotice;
333
+ export {};
334
+ //# sourceMappingURL=notice.d.ts.map