@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
@@ -39,11 +39,15 @@ import { type RandomBytes } from "./view.js";
39
39
  * **It keeps up with a page that changes.** Nodes that arrive after it started
40
40
  * are watched and nodes that leave stop counting, so a band behind a Suspense
41
41
  * boundary, a list that grows, and every region a proposal has just changed are
42
- * measured like the rest. What it does *not* follow is the page becoming a
43
- * different page: the tree and revision are read once, off the root, and every
44
- * batch is filed under them. **A new root, or a new revision in the same root,
45
- * is a new broadcast** — `stop()` the old one and start another, or a
46
- * client-side navigation files its signals under the revision it left.
42
+ * measured like the rest.
43
+ *
44
+ * **And with a page that becomes a different page, when it is handed the
45
+ * document.** The tree and revision are read once off a root element, so a
46
+ * broadcast pointed at an element goes on filing every batch under them — which
47
+ * is a client-side navigation's signals filed against the page it left. Pointed
48
+ * at a `Document` it follows the addressed page instead: a new identity ends one
49
+ * page view and opens another, with its own view key and its own arrival, and
50
+ * the same revision rendered again continues the one it was already observing.
47
51
  */
48
52
  /** The DOM event a batch is dispatched as, on the root element. It bubbles. */
49
53
  /**
@@ -124,17 +128,23 @@ export type ReaderSignalBroadcastError = {
124
128
  readonly detail: string;
125
129
  };
126
130
  /**
127
- * Start broadcasting reader signals from the page under `root`.
131
+ * Start broadcasting reader signals from a rendered Loom page.
132
+ *
133
+ * Hand it the **root element** of the page and it broadcasts from that element:
134
+ * nodes arriving and leaving under it are followed, and the tree and revision
135
+ * are read once, so a page that becomes a different page needs `stop()` and
136
+ * another call or its signals are filed under the revision it left.
128
137
  *
129
- * Returns an error rather than broadcasting nothing when the page is not
130
- * addressed, because a silent broadcaster on an unaddressed page is exactly the
131
- * misconfiguration nobody would notice.
138
+ * Hand it the **document** and it finds the addressed page itself and follows
139
+ * it: a client-side navigation ends one page view and begins another, with its
140
+ * own view key and its own arrival, and the same revision rendered again
141
+ * continues the page view it was already observing
142
+ * ({@link followAddressedPage}). This is the argument to pass in an application
143
+ * that routes on the client, which is most of them.
132
144
  *
133
- * Nodes added under `root` afterwards are picked up and nodes removed stop
134
- * counting. The tree and revision are not: they are read once, here, and a page
135
- * that becomes a different page — a client-side navigation, a re-render at a new
136
- * revision into the same root — needs `stop()` and a new broadcast, or its
137
- * signals are filed under the revision it left.
145
+ * Either way it returns an error rather than broadcasting nothing when there is
146
+ * no addressed page to broadcast from, because a silent broadcaster is exactly
147
+ * the misconfiguration nobody would notice.
138
148
  */
139
- export declare const broadcastReaderSignals: (root: Element, options?: ReaderSignalOptions) => Result<ReaderSignalBroadcast, ReaderSignalBroadcastError>;
149
+ export declare const broadcastReaderSignals: (scope: Element | Document, options?: ReaderSignalOptions) => Result<ReaderSignalBroadcast, ReaderSignalBroadcastError>;
140
150
  //# sourceMappingURL=broadcast.d.ts.map
@@ -1,6 +1,7 @@
1
- import { NAMESPACED_ID_PATTERN, NODE_ID_PATTERN, TREE_ID_PATTERN } from "../grammar.js";
1
+ import { idPattern, NAMESPACED_ID_PATTERN, NODE_ID_PATTERN, TREE_ID_PATTERN } from "../grammar.js";
2
+ import { addressedRootIn } from "../render/addressed.js";
2
3
  import { DISCLOSED_ATTRIBUTE } from "../render/disclosed.js";
3
- import { LOOM_NODE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_TREE_ATTRIBUTE, LOOM_TYPE_ATTRIBUTE, } from "../render/editable.js";
4
+ import { LOOM_AUDIENCE_ATTRIBUTE, LOOM_NODE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_TREE_ATTRIBUTE, LOOM_TYPE_ATTRIBUTE, } from "../render/editable.js";
4
5
  import { err, ok } from "../result.js";
5
6
  import { createSignalLedger } from "./ledger.js";
6
7
  import { READER_SIGNAL_KINDS } from "./kinds.js";
@@ -44,11 +45,15 @@ import { mintViewKey } from "./view.js";
44
45
  * **It keeps up with a page that changes.** Nodes that arrive after it started
45
46
  * are watched and nodes that leave stop counting, so a band behind a Suspense
46
47
  * boundary, a list that grows, and every region a proposal has just changed are
47
- * measured like the rest. What it does *not* follow is the page becoming a
48
- * different page: the tree and revision are read once, off the root, and every
49
- * batch is filed under them. **A new root, or a new revision in the same root,
50
- * is a new broadcast** — `stop()` the old one and start another, or a
51
- * client-side navigation files its signals under the revision it left.
48
+ * measured like the rest.
49
+ *
50
+ * **And with a page that becomes a different page, when it is handed the
51
+ * document.** The tree and revision are read once off a root element, so a
52
+ * broadcast pointed at an element goes on filing every batch under them — which
53
+ * is a client-side navigation's signals filed against the page it left. Pointed
54
+ * at a `Document` it follows the addressed page instead: a new identity ends one
55
+ * page view and opens another, with its own view key and its own arrival, and
56
+ * the same revision rendered again continues the one it was already observing.
52
57
  */
53
58
  /** The DOM event a batch is dispatched as, on the root element. It bubbles. */
54
59
  /**
@@ -93,6 +98,8 @@ const selectionOf = (kinds, types) => {
93
98
  return (kind, type) => enabled.has(kind) && (allowed.get(kind)?.has(type) ?? true);
94
99
  };
95
100
  const DEFAULT_FLUSH_MS = 5000;
101
+ /** A page view nothing has been delivered for yet. */
102
+ const beginPageView = (random) => ({ key: mintViewKey(random), opened: false });
96
103
  /**
97
104
  * On screen means a reader could be reading it: at least
98
105
  * {@link READABLE_VISIBLE_FRACTION} of the element is visible, **or** it fills
@@ -123,6 +130,9 @@ const addressOf = (element) => {
123
130
  const type = element.getAttribute(LOOM_TYPE_ATTRIBUTE);
124
131
  return isNodeId(nodeId) && isPrimitiveType(type) ? { nodeId, type } : undefined;
125
132
  };
133
+ /** The pattern `audienceIdSchema` holds, without the schema library in a reader's bundle. */
134
+ const AUDIENCE_ID_PATTERN = idPattern("aud");
135
+ const isAudienceId = (value) => AUDIENCE_ID_PATTERN.test(value);
126
136
  const pageOf = (root) => {
127
137
  const treeId = root.getAttribute(LOOM_TREE_ATTRIBUTE);
128
138
  /**
@@ -132,12 +142,27 @@ const pageOf = (root) => {
132
142
  */
133
143
  const written = root.getAttribute(LOOM_REVISION_ATTRIBUTE) ?? "";
134
144
  const revision = /^\d+$/.test(written) ? Number(written) : Number.NaN;
135
- return isTreeId(treeId) && Number.isSafeInteger(revision)
136
- ? ok({ treeId, revision })
137
- : err({
145
+ if (!isTreeId(treeId) || !Number.isSafeInteger(revision)) {
146
+ return err({
138
147
  code: "unaddressed",
139
148
  detail: `the root element carries no ${LOOM_TREE_ATTRIBUTE} and ${LOOM_REVISION_ATTRIBUTE}; render the page with addressed: true`,
140
149
  });
150
+ }
151
+ /**
152
+ * Absent is every reader (`aud_everyone`), which is what a page served to no
153
+ * segment says by saying nothing (0284). Present and unreadable is refused
154
+ * rather than ignored: ignoring it would file a segment's page views as
155
+ * everybody's, and the intake would refuse every batch that carried it.
156
+ */
157
+ const audience = root.getAttribute(LOOM_AUDIENCE_ATTRIBUTE);
158
+ if (audience === null)
159
+ return ok({ treeId, revision, audience: undefined });
160
+ return isAudienceId(audience)
161
+ ? ok({ treeId, revision, audience })
162
+ : err({
163
+ code: "unaddressed",
164
+ detail: `the root element's ${LOOM_AUDIENCE_ATTRIBUTE} is not a segment's aud_ id: ${audience}`,
165
+ });
141
166
  };
142
167
  /** The nearest addressed element at or above `element`, without leaving the page. */
143
168
  const nearestAddressed = (root, element) => {
@@ -182,7 +207,8 @@ const deliverSafely = (send, batch) => {
182
207
  }
183
208
  };
184
209
  /**
185
- * Start broadcasting reader signals from the page under `root`.
210
+ * Start broadcasting reader signals from the page under `root`, as part of
211
+ * `of`.
186
212
  *
187
213
  * Returns an error rather than broadcasting nothing when the page is not
188
214
  * addressed, because a silent broadcaster on an unaddressed page is exactly the
@@ -190,35 +216,16 @@ const deliverSafely = (send, batch) => {
190
216
  *
191
217
  * Nodes added under `root` afterwards are picked up and nodes removed stop
192
218
  * counting. The tree and revision are not: they are read once, here, and a page
193
- * that becomes a different page — a client-side navigation, a re-render at a new
194
- * revision into the same root — needs `stop()` and a new broadcast, or its
195
- * signals are filed under the revision it left.
219
+ * that becomes a different page needs another of these — which is what
220
+ * {@link followAddressedPage} does for a host that hands over a `Document`.
196
221
  */
197
- export const broadcastReaderSignals = (root, options = {}) => {
222
+ const broadcastFromRoot = (root, options, of) => {
198
223
  const page = pageOf(root);
199
224
  if (!page.ok)
200
225
  return page;
201
226
  const now = options.now ?? Date.now;
202
227
  const wants = selectionOf(options.kinds, options.types);
203
228
  const document = root.ownerDocument;
204
- /**
205
- * Minted once, here, and carried by every batch this broadcast sends — which
206
- * is what makes the batches of one page view correlatable and two page views
207
- * not (0146). A new broadcast is a new view, including the second one a
208
- * client-side navigation needs, so the key cannot outlive the page it
209
- * describes even by accident.
210
- */
211
- const view = mintViewKey(options.random);
212
- /**
213
- * Whether the opening delivery of this page view has gone.
214
- *
215
- * One batch of a view carries `first` and the rest do not, which is how an
216
- * intake counts a reader arriving exactly once — without it, the only
217
- * countable unit is the delivery, and a reader who stays ten minutes is a
218
- * hundred of them. A new broadcast mints a new view key and gets a new
219
- * opening, which is what a client-side navigation needs.
220
- */
221
- let opened = false;
222
229
  const ledger = createSignalLedger(document.visibilityState === "hidden");
223
230
  let stopped = false;
224
231
  const walks = options.within ?? true;
@@ -253,12 +260,13 @@ export const broadcastReaderSignals = (root, options = {}) => {
253
260
  const batch = {
254
261
  treeId: page.value.treeId,
255
262
  revision: page.value.revision,
263
+ ...(page.value.audience === undefined ? {} : { audience: page.value.audience }),
256
264
  sentAt: now(),
257
- view,
258
- ...(opened ? {} : { first: true }),
265
+ view: of.key,
266
+ ...(of.opened ? {} : { first: true }),
259
267
  signals,
260
268
  };
261
- opened = true;
269
+ of.opened = true;
262
270
  root.dispatchEvent(new CustomEvent(READER_SIGNALS_EVENT, { detail: batch, bubbles: true }));
263
271
  deliverSafely(options.send, batch);
264
272
  };
@@ -498,4 +506,169 @@ export const broadcastReaderSignals = (root, options = {}) => {
498
506
  };
499
507
  return ok({ flush, stop });
500
508
  };
509
+ /**
510
+ * The tree, revision and segment an element says it is, as one comparable
511
+ * value. A page served to another segment is another form of the page, and so
512
+ * another page view, as a new revision is.
513
+ *
514
+ * Read off the attributes rather than off {@link pageOf}, because what this
515
+ * compares is *whether the page changed* and not whether it is addressed well
516
+ * enough to broadcast: a root whose revision goes from `4` to something that is
517
+ * not a number has become a different page and has stopped being a page this
518
+ * can report on, and those are two answers rather than one.
519
+ */
520
+ const identityOf = (root) => [LOOM_TREE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_AUDIENCE_ATTRIBUTE]
521
+ .map((attribute) => root.getAttribute(attribute))
522
+ .join(" ");
523
+ /**
524
+ * Broadcast from whatever addressed page the document holds, and keep
525
+ * broadcasting from it when the host replaces it.
526
+ *
527
+ * ## Why this exists
528
+ *
529
+ * A broadcast reads its tree and revision once, off the root it was handed, and
530
+ * files every batch under them. That is right, and it is why the documented
531
+ * remedy for a page becoming a different page has been *stop and start another*
532
+ * — which asks a host to notice a client-side navigation and do something about
533
+ * it. **A host that does not is the common case, and what it gets is not
534
+ * missing data but wrong data**: a reader navigates from the pricing page to the
535
+ * sign-up page, and every signal from the second page is filed against the
536
+ * first page's nodes under the first page's revision. Nothing says so, at either
537
+ * end — the node ids are real and the batch parses.
538
+ *
539
+ * It is also an undercount at the door. One batch of a page view carries
540
+ * `first`, which is how an arrival is counted exactly once, so a reader who
541
+ * visits four pages in an app that never restarts its broadcast arrives once.
542
+ * Page views by the hour they began in (0356) read that marker, and so does
543
+ * every figure taken at the door's scale.
544
+ *
545
+ * ## What it follows, and what it does not
546
+ *
547
+ * The page's **identity** — its tree and its revision — and not the element
548
+ * carrying it. Three things follow from that, and together they are the
549
+ * counting rule:
550
+ *
551
+ * - **A re-render is not a navigation.** Nodes arriving, leaving and changing
552
+ * under the root are what the broadcast already watches; this notices them,
553
+ * finds the page unchanged, and does nothing. A page a proposal has just
554
+ * rewritten is one page view, as it was before.
555
+ * - **A new identity is a new page view.** A root replaced by a different
556
+ * tree's, or the same root re-rendered at a new revision, ends the page view
557
+ * — the old broadcast is stopped, which delivers what it gathered under the
558
+ * revision it gathered it on — and begins a fresh one, with a fresh view key
559
+ * and a fresh opening. Nothing correlates the two, which is rule 2 of
560
+ * `docs/signals.md` holding rather than being argued about: two page views of
561
+ * two pages are two keys and the reader behind them is not a column anywhere.
562
+ * - **The same identity rendered again is the same page view.** A host that
563
+ * unmounts the element it rendered into and renders the same revision again
564
+ * has not sent a reader anywhere, so the second broadcast is handed the page
565
+ * view the first one was observing: same key, no second opening, no second
566
+ * arrival. This is the case that would double-count, and it is the reason the
567
+ * page view is a value rather than a broadcast's own state.
568
+ *
569
+ * An unaddressed document is refused here exactly as an unaddressed element is
570
+ * refused by a broadcast, and for the same reason. A page that *becomes*
571
+ * unaddressed — the root goes and nothing replaces it — is not a failure: the
572
+ * broadcast is stopped, what it gathered is delivered, and the page view is
573
+ * held in case the same revision comes back.
574
+ *
575
+ * ## What it costs
576
+ *
577
+ * One `MutationObserver` on the document, watching for children and for the two
578
+ * attributes that spell a page's identity. Its callback compares three values
579
+ * it already holds and returns, so the cost of a page that churns is three
580
+ * reads per batch of mutations; the one `querySelector` it can run happens only
581
+ * when the page it was observing is no longer the page in the document. The
582
+ * broadcast itself is unchanged and runs its own observers as it always has.
583
+ */
584
+ const followAddressedPage = (page, options) => {
585
+ const found = addressedRootIn(page);
586
+ if (found === undefined) {
587
+ return err({
588
+ code: "unaddressed",
589
+ detail: `no element in this document carries ${LOOM_TREE_ATTRIBUTE}; render the page with addressed: true`,
590
+ });
591
+ }
592
+ const first = beginPageView(options.random);
593
+ const opening = broadcastFromRoot(found, options, first);
594
+ /**
595
+ * The opening failure is the host's to see, so it is returned. The same
596
+ * failure later is a page this cannot report on rather than a call that went
597
+ * wrong — a root whose revision attribute stops being a number is a page
598
+ * nothing broadcasts from, and the host is not making a call to learn it, so
599
+ * `settled` leaves it unobserved and waits for the next thing to happen.
600
+ */
601
+ if (!opening.ok)
602
+ return opening;
603
+ let observing = {
604
+ root: found,
605
+ identity: identityOf(found),
606
+ of: first,
607
+ broadcast: opening.value,
608
+ };
609
+ /** The page view the last broadcast was observing, while its page may come back. */
610
+ let ended;
611
+ let stopped = false;
612
+ /** Whether the broadcast is still observing the page the document holds. */
613
+ const standing = () => observing !== undefined && observing.root.isConnected && identityOf(observing.root) === observing.identity;
614
+ const settled = () => {
615
+ if (stopped || standing())
616
+ return;
617
+ if (observing !== undefined) {
618
+ observing.broadcast.stop();
619
+ ended = { identity: observing.identity, of: observing.of };
620
+ observing = undefined;
621
+ }
622
+ const root = addressedRootIn(page);
623
+ if (root === undefined)
624
+ return;
625
+ const identity = identityOf(root);
626
+ const of = ended !== undefined && ended.identity === identity ? ended.of : beginPageView(options.random);
627
+ const started = broadcastFromRoot(root, options, of);
628
+ if (!started.ok)
629
+ return;
630
+ observing = { root, identity: identityOf(root), of, broadcast: started.value };
631
+ ended = undefined;
632
+ };
633
+ const pages = new MutationObserver(settled);
634
+ pages.observe(page, {
635
+ childList: true,
636
+ subtree: true,
637
+ attributes: true,
638
+ attributeFilter: [LOOM_TREE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_AUDIENCE_ATTRIBUTE],
639
+ });
640
+ return ok({
641
+ flush: () => observing?.broadcast.flush(),
642
+ stop: () => {
643
+ stopped = true;
644
+ pages.disconnect();
645
+ observing?.broadcast.stop();
646
+ observing = undefined;
647
+ },
648
+ });
649
+ };
650
+ /** A document rather than an element, by node type — which is a number every realm agrees on (0354). */
651
+ const isDocument = (scope) => scope.nodeType === 9;
652
+ /**
653
+ * Start broadcasting reader signals from a rendered Loom page.
654
+ *
655
+ * Hand it the **root element** of the page and it broadcasts from that element:
656
+ * nodes arriving and leaving under it are followed, and the tree and revision
657
+ * are read once, so a page that becomes a different page needs `stop()` and
658
+ * another call or its signals are filed under the revision it left.
659
+ *
660
+ * Hand it the **document** and it finds the addressed page itself and follows
661
+ * it: a client-side navigation ends one page view and begins another, with its
662
+ * own view key and its own arrival, and the same revision rendered again
663
+ * continues the page view it was already observing
664
+ * ({@link followAddressedPage}). This is the argument to pass in an application
665
+ * that routes on the client, which is most of them.
666
+ *
667
+ * Either way it returns an error rather than broadcasting nothing when there is
668
+ * no addressed page to broadcast from, because a silent broadcaster is exactly
669
+ * the misconfiguration nobody would notice.
670
+ */
671
+ export const broadcastReaderSignals = (scope, options = {}) => isDocument(scope)
672
+ ? followAddressedPage(scope, options)
673
+ : broadcastFromRoot(scope, options, beginPageView(options.random));
501
674
  //# sourceMappingURL=broadcast.js.map
@@ -4,32 +4,41 @@ import type { ReaderSignalJournal, ReaderSignalStoreError, ReceivedBatch } from
4
4
  import { type FunnelPair } from "./rollup.js";
5
5
  import type { ReaderTallyStore } from "./tally.js";
6
6
  /**
7
- * The one operation that empties the buffer.
7
+ * The one operation that counts the buffer.
8
8
  *
9
9
  * `journal.ts` can hold batches, `rollup.ts` can fold them and `tally.ts` can
10
10
  * keep what the fold produced — and until this module existed nothing joined
11
11
  * the three, so a deployment with signals switched on accumulated the largest
12
12
  * table it owns and counted none of it.
13
13
  *
14
- * **Counting and forgetting are one call, and that is the design rather than a
15
- * convenience.** A rollup reports *what this window added* (0147), so a batch
16
- * counted twice is counted twice forever: there is no idempotence to fall back
17
- * on and no way to notice afterwards, because the wrong number looks exactly
18
- * like a busy afternoon. The only defence that does not need durable bookkeeping
19
- * is for the set of batches rolled up and the set forgotten to be the same set,
20
- * decided once, in one place. That is this file, and it is why there is no
21
- * exported `applyReaderSignalRetention` beside it — a function that can forget
22
- * without counting is the data-loss bug, and one that can count without
23
- * forgetting is the double-count bug.
14
+ * **Counting and recording that it happened are one call, and that is the
15
+ * design rather than a convenience.** A rollup reports *what this window
16
+ * added* (0147), so a batch counted twice is counted twice forever: there is no
17
+ * idempotence to fall back on and no way to notice afterwards, because the
18
+ * wrong number looks exactly like a busy afternoon. The only defence that does
19
+ * not need durable bookkeeping is for the set of batches rolled up and the set
20
+ * marked as counted to be the same set, decided once, in one place. That is
21
+ * this file.
22
+ *
23
+ * **Until 5 November the mark was a delete** (0146), and the sentence above
24
+ * said *forgotten* where it now says *marked*. A delivery is now kept for the
25
+ * window its deployment states — thirty days by default, so that an operator
26
+ * can look at individual deliveries rather than only at counters (0349) — and
27
+ * deleted by a second sweep in `expire.ts`. What did not change is the thing
28
+ * the invariant protects: this run decides one prefix, counts it, and records
29
+ * that it counted it, and no other operation may touch that decision. What that
30
+ * split buys is that the two failures are no longer the same failure. A sweep
31
+ * that deletes without counting loses deliveries; this cannot delete at all.
24
32
  *
25
33
  * Nothing schedules it, for the reason nothing schedules telemetry's retention
26
- * or `auditSnapshot`: when a deployment forgets is an operational choice, and a
27
- * framework that quietly deleted a host's data on a timer it chose would be
28
- * making it. A host calls this from a cron route, a deploy hook, or by hand.
34
+ * or `auditSnapshot`: when a deployment counts is an operational choice, and a
35
+ * framework that quietly swept a host's data on a timer it chose would be
36
+ * making it. A host calls this from a cron route, a deploy hook, or by hand,
37
+ * and calls {@link expireReaderEvents} from the same place.
29
38
  *
30
39
  * **One run at a time, and the caller is what makes that true.** Two runs over
31
40
  * the same ripe prefix both roll it up and both apply; applying is additive
32
- * (0147), so the counters double and the buffer empties once, leaving nothing
41
+ * (0147), so the counters double and the prefix is marked once, leaving nothing
33
42
  * behind that could say what happened. Nothing here can prevent it — a journal
34
43
  * and a store are two handles with no shared transaction between them — so
35
44
  * serialising belongs to whatever schedules this. `apps/loom/scripts/
@@ -37,8 +46,8 @@ import type { ReaderTallyStore } from "./tally.js";
37
46
  * cheapest thing that works for a cron that overruns its own interval.
38
47
  */
39
48
  /**
40
- * The window is the age a batch reaches before it is counted and dropped, and
41
- * it is two arguments pulling opposite ways.
49
+ * The window is the age a batch reaches before it is counted, and it is two
50
+ * arguments pulling opposite ways.
42
51
  *
43
52
  * **Longer is more accurate.** `views` and `reached` count distinct page views,
44
53
  * distinctness does not add up, and a page view whose batches straddle two
@@ -56,10 +65,15 @@ import type { ReaderTallyStore } from "./tally.js";
56
65
  * allows — the openings waiting are otherwise indistinguishable from the
57
66
  * ordinary one-window lag this setting creates (0274).
58
67
  *
59
- * **Shorter is more anonymous.** The raw window is the entire mechanism by
60
- * which a view key stops existing (0146). The key is opaque, random and
61
- * correlates nothing outside the buffer, but it correlates that, and the
62
- * argument for it rests on how briefly it lives.
68
+ * **Shorter is more anonymous — and since 5 November this is no longer the
69
+ * window that governs that.** The view key stops existing when the row holding
70
+ * it is deleted, and that is now the kept window rather than this one
71
+ * (0349, 0351): a delivery is counted at this age and deleted at the age
72
+ * `expire.ts` is given. This setting still decides how much over-count a
73
+ * straddling page view causes, which is the accuracy argument above; what it no
74
+ * longer decides is how long a page view's signals stay correlatable. That
75
+ * number is `DEFAULT_READER_EVENT_RETENTION_MS` and the tension in it is
76
+ * recorded rather than hidden.
63
77
  *
64
78
  * An hour is long against a page view and short against a day, which is why it
65
79
  * is the default rather than a constant: rule 5 of `docs/signals.md` makes the
@@ -95,6 +109,19 @@ export type ReaderSignalWindow = z.infer<typeof readerSignalWindowSchema>;
95
109
  */
96
110
  export declare const DEFAULT_COLLECTION_SCAN = 5000;
97
111
  export declare const MAX_COLLECTION_SCAN = 50000;
112
+ /**
113
+ * A pair as a deployment asks it: the question, where it is asked, and the
114
+ * instant it began being asked.
115
+ *
116
+ * `countedFrom` is epoch milliseconds and is the whole of 0418's second half:
117
+ * a run whose window **begins** before that instant does not ask the question
118
+ * at all, and says so in its outcome. Absent means no start — the shape every
119
+ * pair had before, and the right one for a question a deployment has always
120
+ * asked.
121
+ */
122
+ export type AskedFunnelPair = FunnelPair & {
123
+ readonly countedFrom?: number;
124
+ };
98
125
  export type CollectionRequest = {
99
126
  readonly windowMs?: number;
100
127
  /**
@@ -105,8 +132,13 @@ export type CollectionRequest = {
105
132
  * already folded, because the batches those answers came from are gone. That
106
133
  * is the price of aggregates being the durable artefact and it is worth
107
134
  * knowing before a deployment waits a day for a number it will not get.
135
+ *
136
+ * **A pair carrying `countedFrom` is held back until a whole window is after
137
+ * it** (0418), rather than counted over whatever the first run happens to
138
+ * reach: a figure a screen labels *counting since Tuesday* must not hold
139
+ * readers from Monday.
108
140
  */
109
- readonly pairs?: readonly FunnelPair[];
141
+ readonly pairs?: readonly AskedFunnelPair[];
110
142
  readonly clock?: Clock;
111
143
  readonly scanLimit?: number;
112
144
  };
@@ -128,12 +160,63 @@ export type CollectionPlan = {
128
160
  readonly waiting: number;
129
161
  };
130
162
  export declare const collectionPlanOf: (scanned: readonly ReceivedBatch[], horizon: string) => CollectionPlan;
163
+ /** What a run may ask, and how many questions it held back (0418). */
164
+ export type FunnelsAsked = {
165
+ readonly asking: readonly FunnelPair[];
166
+ readonly withheld: number;
167
+ };
168
+ /**
169
+ * The pairs a run folding a window that **begins** at `from` may ask, and the
170
+ * count of the ones it may not.
171
+ *
172
+ * The comparison is against the oldest delivery in the window rather than
173
+ * against the run's own clock, and that is the whole of the rule: every
174
+ * delivery this run folds arrived at or after `from`, so a question whose start
175
+ * is at or before `from` is answered over readers who all arrived after it was
176
+ * asked. A question asked in the middle of a window is held back one run, which
177
+ * costs one window of an answer and buys a figure that means what its label
178
+ * says.
179
+ *
180
+ * **An unreadable instant withholds every question with a start**, because the
181
+ * fallback is the one that cannot be noticed: counting a step from a window
182
+ * nobody can place is a figure nobody can date.
183
+ */
184
+ export declare const funnelsAskedOf: (pairs: readonly AskedFunnelPair[], from: string) => FunnelsAsked;
131
185
  export declare const horizonOf: (configured: ReaderSignalWindow, now: string) => string | null;
132
186
  /** The half of the outcome a caller shows or logs, with nothing in it about a reader. */
133
187
  export type CollectionSummary = {
134
188
  readonly counted: number;
135
189
  readonly tallies: number;
136
190
  readonly funnels: number;
191
+ /**
192
+ * Funnel pairs this run was handed and did not ask, because the window it
193
+ * folded begins before the pair was first asked (0418).
194
+ *
195
+ * In the run's outcome rather than anywhere durable, for `redelivered`'s
196
+ * reason: a fold's own figures are not the artefact. Non-zero is the ordinary
197
+ * answer on the run after a step is set and a sign of something to look at
198
+ * if it stays non-zero — a deployment permanently behind on collection never
199
+ * reaches a window that starts after its newest question.
200
+ */
201
+ readonly withheldFunnels: number;
202
+ /**
203
+ * Hourly rows this run wrote for what readers did (`acted.ts`).
204
+ *
205
+ * A slice of the tallies rather than a figure beside them: a window in which
206
+ * nobody pressed, opened or sent anything writes none, however many tallies
207
+ * it wrote, because the counter holds what readers *did* and a page being on
208
+ * screen is not one of those.
209
+ */
210
+ readonly acted: number;
211
+ /**
212
+ * Hourly rows this run wrote for the funnels it was asked (`funnel-hours.ts`).
213
+ *
214
+ * A cut of the answers rather than a figure beside them: a window in which
215
+ * nobody reached a pair's first end writes none, however many answers it
216
+ * wrote, because an answer is written at nought for a question a deployment
217
+ * asked and an hour is written only where somebody entered the funnel.
218
+ */
219
+ readonly funnelHours: number;
137
220
  /** Distinct page views the window held. */
138
221
  readonly views: number;
139
222
  /**
@@ -154,31 +237,40 @@ export type CollectionSummary = {
154
237
  */
155
238
  readonly redelivered: number;
156
239
  /**
157
- * How old the oldest delivery the scan found was, in milliseconds, at the
158
- * instant this run was taken.
240
+ * How old the oldest **uncounted** delivery the scan found was, in
241
+ * milliseconds, at the instant this run was taken.
159
242
  *
160
243
  * A fact about the buffer and about no reader, like every other figure here.
161
- * It is free: a scan runs from the oldest end, so the first batch it read is
162
- * the oldest one there is, and this is one subtraction over it.
244
+ * It is free: a scan runs from the oldest uncounted end, so the first batch
245
+ * it read is the oldest one waiting, and this is one subtraction over it.
163
246
  *
164
247
  * **The run does the subtraction rather than the caller**, because the
165
248
  * caller's clock is not this run's: a surface that read the age against its
166
249
  * own `now` would publish a number nothing had measured.
167
250
  *
251
+ * **It is the fold's lag, not the kept window** (0351). It was both while a
252
+ * counted delivery was deleted in the same breath, which is why
253
+ * `retentionPromiseOf` used to be handed this outcome; the ceiling readers
254
+ * are promised is now about deletion, so that reading is handed the expiry
255
+ * run's own figure and this one answers the question it still owns — how far
256
+ * behind collection is.
257
+ *
168
258
  * Never absent and always at least the ripeness window: a summary exists only
169
- * where something was ripe. What it is for is
170
- * {@link retentionPromiseOf} — whether the ceiling the deployment publishes
171
- * to its readers is one it keeps. A delivery whose stored instant cannot be
172
- * read leaves this not a number, and that reading answers *nothing here can
173
- * say* on it rather than *kept*.
259
+ * where something was ripe.
174
260
  */
175
261
  readonly oldestMs: number;
176
262
  };
177
263
  export type CollectionOutcome = {
178
264
  readonly outcome: "collected";
179
265
  readonly summary: CollectionSummary;
180
- /** Rows the buffer removed. Below `counted` only if something else pruned first. */
181
- readonly removed: number;
266
+ /**
267
+ * Rows this run marked as counted.
268
+ *
269
+ * Below `counted` only where something had already marked them — which on
270
+ * one run at a time is nothing, and is why a figure below the count is
271
+ * worth seeing rather than a rounding difference.
272
+ */
273
+ readonly recorded: number;
182
274
  /** The scan filled its limit with ripe batches, so another run has work now. */
183
275
  readonly more: boolean;
184
276
  }
@@ -188,35 +280,37 @@ export type CollectionOutcome = {
188
280
  readonly waiting: number;
189
281
  }
190
282
  /**
191
- * The counters took the window and the buffer would not drop it.
283
+ * The counters took the window and the journal would not record it.
192
284
  *
193
285
  * Its own outcome because it is the one state that gets worse if it is
194
- * ignored: the batches are durable in the counters and still in the buffer,
195
- * so the next run counts them again. An operator seeing this prunes below the
196
- * reported position by hand, or fixes the buffer before the next run.
286
+ * ignored: the batches are durable in the counters and still unmarked, so the
287
+ * next run counts them again. An operator seeing this marks the prefix by
288
+ * hand, or fixes the store before the next run — and must not reach for a
289
+ * delete, which would lose the deliveries and leave the double-count.
197
290
  */
198
291
  | {
199
- readonly outcome: "counted-not-forgotten";
292
+ readonly outcome: "counted-not-recorded";
200
293
  readonly summary: CollectionSummary;
201
294
  readonly before: number;
202
295
  readonly error: ReaderSignalStoreError;
203
296
  }
204
- /** The window was not usable. Nothing was read, counted or deleted. */
297
+ /** The window was not usable. Nothing was read, counted or marked. */
205
298
  | {
206
299
  readonly outcome: "refused";
207
300
  readonly reason: string;
208
301
  }
209
- /** Read or write failed before anything became durable. Nothing was deleted. */
302
+ /** Read or write failed before anything became durable. Nothing was marked. */
210
303
  | {
211
304
  readonly outcome: "unavailable";
212
305
  readonly error: ReaderSignalStoreError;
213
306
  };
214
307
  /**
215
- * Count a window of the buffer into the durable counters, then drop it.
308
+ * Count a window of the buffer into the durable counters, then record that it
309
+ * was counted.
216
310
  *
217
311
  * The order is the safe one and the reverse is a data-loss bug that looks like
218
- * a feature working: aggregates first, the buffer second. What that leaves is
219
- * `counted-not-forgotten`, which is visible and recoverable — the opposite
312
+ * a feature working: aggregates first, the mark second. What that leaves is
313
+ * `counted-not-recorded`, which is visible and recoverable — the opposite
220
314
  * order's failure is neither.
221
315
  */
222
316
  export declare const collectReaderSignals: (journal: ReaderSignalJournal, store: ReaderTallyStore, request?: CollectionRequest) => Promise<CollectionOutcome>;