@jam-overture/loom 0.1.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 (401) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +743 -0
  3. package/dist/catalogue.d.ts +70 -0
  4. package/dist/catalogue.js +88 -0
  5. package/dist/cli/args.d.ts +17 -0
  6. package/dist/cli/args.js +83 -0
  7. package/dist/cli/filesystem.d.ts +15 -0
  8. package/dist/cli/filesystem.js +31 -0
  9. package/dist/cli/index.d.ts +12 -0
  10. package/dist/cli/index.js +12 -0
  11. package/dist/cli/main.d.ts +3 -0
  12. package/dist/cli/main.js +30 -0
  13. package/dist/cli/namespace.d.ts +40 -0
  14. package/dist/cli/namespace.js +40 -0
  15. package/dist/cli/plan.d.ts +84 -0
  16. package/dist/cli/plan.js +113 -0
  17. package/dist/cli/run.d.ts +17 -0
  18. package/dist/cli/run.js +75 -0
  19. package/dist/cli/templates.d.ts +43 -0
  20. package/dist/cli/templates.js +134 -0
  21. package/dist/closed-set.d.ts +34 -0
  22. package/dist/closed-set.js +34 -0
  23. package/dist/data/adapter.d.ts +123 -0
  24. package/dist/data/adapter.js +91 -0
  25. package/dist/data/binding.d.ts +48 -0
  26. package/dist/data/binding.js +39 -0
  27. package/dist/data/catalogue.d.ts +26 -0
  28. package/dist/data/catalogue.js +6 -0
  29. package/dist/data/index.d.ts +14 -0
  30. package/dist/data/index.js +14 -0
  31. package/dist/data/plan.d.ts +58 -0
  32. package/dist/data/plan.js +0 -0
  33. package/dist/data/resolution.d.ts +91 -0
  34. package/dist/data/resolution.js +96 -0
  35. package/dist/data/resolve.d.ts +46 -0
  36. package/dist/data/resolve.js +37 -0
  37. package/dist/data/source.d.ts +40 -0
  38. package/dist/data/source.js +45 -0
  39. package/dist/deadline.d.ts +57 -0
  40. package/dist/deadline.js +78 -0
  41. package/dist/frame/catalogue.d.ts +24 -0
  42. package/dist/frame/catalogue.js +5 -0
  43. package/dist/frame/index.d.ts +12 -0
  44. package/dist/frame/index.js +12 -0
  45. package/dist/frame/origin.d.ts +87 -0
  46. package/dist/frame/origin.js +114 -0
  47. package/dist/frame/resolution.d.ts +85 -0
  48. package/dist/frame/resolution.js +79 -0
  49. package/dist/grammar.d.ts +26 -0
  50. package/dist/grammar.js +28 -0
  51. package/dist/ids.d.ts +57 -0
  52. package/dist/ids.js +104 -0
  53. package/dist/index.d.ts +26 -0
  54. package/dist/index.js +26 -0
  55. package/dist/interactivity.d.ts +50 -0
  56. package/dist/interactivity.js +22 -0
  57. package/dist/interpretation/anthropic.d.ts +22 -0
  58. package/dist/interpretation/anthropic.js +76 -0
  59. package/dist/interpretation/client.d.ts +83 -0
  60. package/dist/interpretation/client.js +2 -0
  61. package/dist/interpretation/draft.d.ts +234 -0
  62. package/dist/interpretation/draft.js +84 -0
  63. package/dist/interpretation/index.d.ts +15 -0
  64. package/dist/interpretation/index.js +15 -0
  65. package/dist/interpretation/interpreter.d.ts +62 -0
  66. package/dist/interpretation/interpreter.js +151 -0
  67. package/dist/interpretation/materialize.d.ts +42 -0
  68. package/dist/interpretation/materialize.js +107 -0
  69. package/dist/interpretation/prompt.d.ts +229 -0
  70. package/dist/interpretation/prompt.js +285 -0
  71. package/dist/interpretation/render.d.ts +76 -0
  72. package/dist/interpretation/render.js +272 -0
  73. package/dist/interpretation/schema.d.ts +49 -0
  74. package/dist/interpretation/schema.js +131 -0
  75. package/dist/json.d.ts +35 -0
  76. package/dist/json.js +11 -0
  77. package/dist/paging.d.ts +60 -0
  78. package/dist/paging.js +49 -0
  79. package/dist/primitive-type.d.ts +32 -0
  80. package/dist/primitive-type.js +39 -0
  81. package/dist/render/addressing.d.ts +59 -0
  82. package/dist/render/addressing.js +60 -0
  83. package/dist/render/anchor.d.ts +105 -0
  84. package/dist/render/anchor.js +84 -0
  85. package/dist/render/behaviour-adjust.d.ts +62 -0
  86. package/dist/render/behaviour-adjust.js +78 -0
  87. package/dist/render/behaviour-copy.d.ts +53 -0
  88. package/dist/render/behaviour-copy.js +75 -0
  89. package/dist/render/behaviour-disclose.d.ts +74 -0
  90. package/dist/render/behaviour-disclose.js +77 -0
  91. package/dist/render/behaviour-present.d.ts +123 -0
  92. package/dist/render/behaviour-present.js +173 -0
  93. package/dist/render/behaviour.d.ts +243 -0
  94. package/dist/render/behaviour.js +284 -0
  95. package/dist/render/control.d.ts +81 -0
  96. package/dist/render/control.js +80 -0
  97. package/dist/render/decorative.d.ts +62 -0
  98. package/dist/render/decorative.js +2 -0
  99. package/dist/render/diagnostics.d.ts +260 -0
  100. package/dist/render/diagnostics.js +61 -0
  101. package/dist/render/disclosed.d.ts +37 -0
  102. package/dist/render/disclosed.js +37 -0
  103. package/dist/render/editable.d.ts +34 -0
  104. package/dist/render/editable.js +35 -0
  105. package/dist/render/frame.d.ts +42 -0
  106. package/dist/render/frame.js +31 -0
  107. package/dist/render/index.d.ts +35 -0
  108. package/dist/render/index.js +35 -0
  109. package/dist/render/inline-variables.d.ts +77 -0
  110. package/dist/render/inline-variables.js +220 -0
  111. package/dist/render/presented.d.ts +82 -0
  112. package/dist/render/presented.js +82 -0
  113. package/dist/render/primitive.d.ts +228 -0
  114. package/dist/render/primitive.js +36 -0
  115. package/dist/render/props.d.ts +48 -0
  116. package/dist/render/props.js +2 -0
  117. package/dist/render/reads.d.ts +73 -0
  118. package/dist/render/reads.js +45 -0
  119. package/dist/render/render.d.ts +164 -0
  120. package/dist/render/render.js +571 -0
  121. package/dist/render/request.d.ts +111 -0
  122. package/dist/render/request.js +60 -0
  123. package/dist/render/text.d.ts +91 -0
  124. package/dist/render/text.js +44 -0
  125. package/dist/render/theme.d.ts +61 -0
  126. package/dist/render/theme.js +52 -0
  127. package/dist/reserved-props.d.ts +35 -0
  128. package/dist/reserved-props.js +45 -0
  129. package/dist/result.d.ts +27 -0
  130. package/dist/result.js +30 -0
  131. package/dist/role.d.ts +71 -0
  132. package/dist/role.js +22 -0
  133. package/dist/runtime/analysis.d.ts +149 -0
  134. package/dist/runtime/analysis.js +187 -0
  135. package/dist/runtime/assessment.d.ts +35 -0
  136. package/dist/runtime/assessment.js +13 -0
  137. package/dist/runtime/disposition.d.ts +102 -0
  138. package/dist/runtime/disposition.js +59 -0
  139. package/dist/runtime/events.d.ts +187 -0
  140. package/dist/runtime/events.js +7 -0
  141. package/dist/runtime/gate.d.ts +43 -0
  142. package/dist/runtime/gate.js +169 -0
  143. package/dist/runtime/index.d.ts +27 -0
  144. package/dist/runtime/index.js +27 -0
  145. package/dist/runtime/intent.d.ts +60 -0
  146. package/dist/runtime/intent.js +36 -0
  147. package/dist/runtime/interpreter.d.ts +117 -0
  148. package/dist/runtime/interpreter.js +46 -0
  149. package/dist/runtime/inverse-interpreter.d.ts +90 -0
  150. package/dist/runtime/inverse-interpreter.js +56 -0
  151. package/dist/runtime/inverse.d.ts +87 -0
  152. package/dist/runtime/inverse.js +48 -0
  153. package/dist/runtime/narration.d.ts +24 -0
  154. package/dist/runtime/narration.js +36 -0
  155. package/dist/runtime/nesting.d.ts +31 -0
  156. package/dist/runtime/nesting.js +46 -0
  157. package/dist/runtime/pipeline.d.ts +124 -0
  158. package/dist/runtime/pipeline.js +178 -0
  159. package/dist/runtime/policy-fingerprint.d.ts +29 -0
  160. package/dist/runtime/policy-fingerprint.js +119 -0
  161. package/dist/runtime/policy-source.d.ts +42 -0
  162. package/dist/runtime/policy-source.js +8 -0
  163. package/dist/runtime/policy.d.ts +156 -0
  164. package/dist/runtime/policy.js +107 -0
  165. package/dist/runtime/proposal.d.ts +423 -0
  166. package/dist/runtime/proposal.js +109 -0
  167. package/dist/runtime/redirection.d.ts +53 -0
  168. package/dist/runtime/redirection.js +38 -0
  169. package/dist/runtime/repointing.d.ts +71 -0
  170. package/dist/runtime/repointing.js +0 -0
  171. package/dist/runtime/reversibility.d.ts +36 -0
  172. package/dist/runtime/reversibility.js +39 -0
  173. package/dist/runtime/stake-level.d.ts +33 -0
  174. package/dist/runtime/stake-level.js +58 -0
  175. package/dist/runtime/stakes.d.ts +47 -0
  176. package/dist/runtime/stakes.js +305 -0
  177. package/dist/runtime/vocabulary.d.ts +122 -0
  178. package/dist/runtime/vocabulary.js +87 -0
  179. package/dist/sdk/audit.d.ts +195 -0
  180. package/dist/sdk/audit.js +128 -0
  181. package/dist/sdk/catalogue.d.ts +37 -0
  182. package/dist/sdk/catalogue.js +16 -0
  183. package/dist/sdk/conformance.d.ts +342 -0
  184. package/dist/sdk/conformance.js +494 -0
  185. package/dist/sdk/copy.d.ts +105 -0
  186. package/dist/sdk/copy.js +90 -0
  187. package/dist/sdk/definition.d.ts +242 -0
  188. package/dist/sdk/definition.js +64 -0
  189. package/dist/sdk/index.d.ts +19 -0
  190. package/dist/sdk/index.js +19 -0
  191. package/dist/sdk/interactivity.d.ts +29 -0
  192. package/dist/sdk/interactivity.js +34 -0
  193. package/dist/sdk/pairings.d.ts +124 -0
  194. package/dist/sdk/pairings.js +81 -0
  195. package/dist/sdk/registry.d.ts +162 -0
  196. package/dist/sdk/registry.js +329 -0
  197. package/dist/sdk/selection.d.ts +46 -0
  198. package/dist/sdk/selection.js +24 -0
  199. package/dist/sdk/text.d.ts +100 -0
  200. package/dist/sdk/text.js +105 -0
  201. package/dist/sdk/vocabulary.d.ts +39 -0
  202. package/dist/sdk/vocabulary.js +36 -0
  203. package/dist/signals/broadcast.d.ts +134 -0
  204. package/dist/signals/broadcast.js +451 -0
  205. package/dist/signals/collect.d.ts +184 -0
  206. package/dist/signals/collect.js +196 -0
  207. package/dist/signals/deliver.d.ts +64 -0
  208. package/dist/signals/deliver.js +85 -0
  209. package/dist/signals/fold.d.ts +112 -0
  210. package/dist/signals/fold.js +76 -0
  211. package/dist/signals/index.d.ts +31 -0
  212. package/dist/signals/index.js +31 -0
  213. package/dist/signals/ingest.d.ts +51 -0
  214. package/dist/signals/ingest.js +70 -0
  215. package/dist/signals/intake.d.ts +149 -0
  216. package/dist/signals/intake.js +154 -0
  217. package/dist/signals/journal.d.ts +94 -0
  218. package/dist/signals/journal.js +11 -0
  219. package/dist/signals/kinds.d.ts +22 -0
  220. package/dist/signals/kinds.js +22 -0
  221. package/dist/signals/ledger.d.ts +46 -0
  222. package/dist/signals/ledger.js +81 -0
  223. package/dist/signals/memory.d.ts +17 -0
  224. package/dist/signals/memory.js +99 -0
  225. package/dist/signals/migrate.d.ts +27 -0
  226. package/dist/signals/migrate.js +78 -0
  227. package/dist/signals/postgres.d.ts +7 -0
  228. package/dist/signals/postgres.js +295 -0
  229. package/dist/signals/rollup.d.ts +142 -0
  230. package/dist/signals/rollup.js +0 -0
  231. package/dist/signals/schema.d.ts +534 -0
  232. package/dist/signals/schema.js +92 -0
  233. package/dist/signals/signal.d.ts +381 -0
  234. package/dist/signals/signal.js +150 -0
  235. package/dist/signals/tally.d.ts +70 -0
  236. package/dist/signals/tally.js +2 -0
  237. package/dist/signals/view.d.ts +51 -0
  238. package/dist/signals/view.js +54 -0
  239. package/dist/store/attribution.d.ts +125 -0
  240. package/dist/store/attribution.js +116 -0
  241. package/dist/store/database.d.ts +14 -0
  242. package/dist/store/database.js +2 -0
  243. package/dist/store/driver.d.ts +29 -0
  244. package/dist/store/driver.js +39 -0
  245. package/dist/store/errors.d.ts +56 -0
  246. package/dist/store/errors.js +37 -0
  247. package/dist/store/index.d.ts +16 -0
  248. package/dist/store/index.js +16 -0
  249. package/dist/store/memory.d.ts +3 -0
  250. package/dist/store/memory.js +115 -0
  251. package/dist/store/migrate.d.ts +54 -0
  252. package/dist/store/migrate.js +122 -0
  253. package/dist/store/postgres-holds.d.ts +4 -0
  254. package/dist/store/postgres-holds.js +192 -0
  255. package/dist/store/postgres.d.ts +8 -0
  256. package/dist/store/postgres.js +262 -0
  257. package/dist/store/replay.d.ts +94 -0
  258. package/dist/store/replay.js +82 -0
  259. package/dist/store/revert.d.ts +116 -0
  260. package/dist/store/revert.js +243 -0
  261. package/dist/store/schema.d.ts +371 -0
  262. package/dist/store/schema.js +78 -0
  263. package/dist/store/source.d.ts +23 -0
  264. package/dist/store/source.js +37 -0
  265. package/dist/store/store.d.ts +231 -0
  266. package/dist/store/store.js +52 -0
  267. package/dist/store/undone.d.ts +18 -0
  268. package/dist/store/undone.js +89 -0
  269. package/dist/submit/catalogue.d.ts +20 -0
  270. package/dist/submit/catalogue.js +5 -0
  271. package/dist/submit/declaration.d.ts +39 -0
  272. package/dist/submit/declaration.js +30 -0
  273. package/dist/submit/endpoint.d.ts +131 -0
  274. package/dist/submit/endpoint.js +160 -0
  275. package/dist/submit/index.d.ts +13 -0
  276. package/dist/submit/index.js +13 -0
  277. package/dist/submit/plan.d.ts +49 -0
  278. package/dist/submit/plan.js +47 -0
  279. package/dist/submit/resolution.d.ts +61 -0
  280. package/dist/submit/resolution.js +64 -0
  281. package/dist/submit/resolve.d.ts +45 -0
  282. package/dist/submit/resolve.js +36 -0
  283. package/dist/telemetry/calibration.d.ts +132 -0
  284. package/dist/telemetry/calibration.js +151 -0
  285. package/dist/telemetry/episode.d.ts +140 -0
  286. package/dist/telemetry/episode.js +272 -0
  287. package/dist/telemetry/event.d.ts +2310 -0
  288. package/dist/telemetry/event.js +405 -0
  289. package/dist/telemetry/index.d.ts +15 -0
  290. package/dist/telemetry/index.js +15 -0
  291. package/dist/telemetry/journal.d.ts +116 -0
  292. package/dist/telemetry/journal.js +11 -0
  293. package/dist/telemetry/memory.d.ts +24 -0
  294. package/dist/telemetry/memory.js +75 -0
  295. package/dist/telemetry/migrate.d.ts +26 -0
  296. package/dist/telemetry/migrate.js +40 -0
  297. package/dist/telemetry/postgres.d.ts +6 -0
  298. package/dist/telemetry/postgres.js +139 -0
  299. package/dist/telemetry/retention.d.ts +131 -0
  300. package/dist/telemetry/retention.js +217 -0
  301. package/dist/telemetry/schema.d.ts +113 -0
  302. package/dist/telemetry/schema.js +33 -0
  303. package/dist/telemetry/sink.d.ts +42 -0
  304. package/dist/telemetry/sink.js +61 -0
  305. package/dist/testing/contracts.d.ts +34 -0
  306. package/dist/testing/contracts.js +34 -0
  307. package/dist/testing/definitions.d.ts +15 -0
  308. package/dist/testing/definitions.js +48 -0
  309. package/dist/testing/doubles.d.ts +94 -0
  310. package/dist/testing/doubles.js +141 -0
  311. package/dist/testing/episode-harness.d.ts +49 -0
  312. package/dist/testing/episode-harness.js +65 -0
  313. package/dist/testing/filesystem.d.ts +17 -0
  314. package/dist/testing/filesystem.js +17 -0
  315. package/dist/testing/fixtures.d.ts +57 -0
  316. package/dist/testing/fixtures.js +84 -0
  317. package/dist/testing/hold-contract.d.ts +19 -0
  318. package/dist/testing/hold-contract.js +374 -0
  319. package/dist/testing/index.d.ts +41 -0
  320. package/dist/testing/index.js +41 -0
  321. package/dist/testing/journal-contract.d.ts +17 -0
  322. package/dist/testing/journal-contract.js +353 -0
  323. package/dist/testing/model-replies.d.ts +34 -0
  324. package/dist/testing/model-replies.js +101 -0
  325. package/dist/testing/primitives.d.ts +7 -0
  326. package/dist/testing/primitives.js +29 -0
  327. package/dist/testing/reader-signal-contract.d.ts +38 -0
  328. package/dist/testing/reader-signal-contract.js +318 -0
  329. package/dist/testing/row-security.d.ts +17 -0
  330. package/dist/testing/row-security.js +21 -0
  331. package/dist/testing/store-contract.d.ts +25 -0
  332. package/dist/testing/store-contract.js +500 -0
  333. package/dist/theme/apply.d.ts +17 -0
  334. package/dist/theme/apply.js +60 -0
  335. package/dist/theme/contrast.d.ts +197 -0
  336. package/dist/theme/contrast.js +259 -0
  337. package/dist/theme/derive.d.ts +77 -0
  338. package/dist/theme/derive.js +167 -0
  339. package/dist/theme/faces.d.ts +73 -0
  340. package/dist/theme/faces.js +119 -0
  341. package/dist/theme/font-packs.d.ts +25 -0
  342. package/dist/theme/font-packs.js +257 -0
  343. package/dist/theme/index.d.ts +20 -0
  344. package/dist/theme/index.js +20 -0
  345. package/dist/theme/lab.d.ts +30 -0
  346. package/dist/theme/lab.js +46 -0
  347. package/dist/theme/library.d.ts +114 -0
  348. package/dist/theme/library.js +300 -0
  349. package/dist/theme/measure.d.ts +144 -0
  350. package/dist/theme/measure.js +145 -0
  351. package/dist/theme/palettes.d.ts +64 -0
  352. package/dist/theme/palettes.js +497 -0
  353. package/dist/theme/registry.d.ts +59 -0
  354. package/dist/theme/registry.js +60 -0
  355. package/dist/theme/separation.d.ts +177 -0
  356. package/dist/theme/separation.js +203 -0
  357. package/dist/theme/style-presets.d.ts +60 -0
  358. package/dist/theme/style-presets.js +124 -0
  359. package/dist/theme/theme.d.ts +253 -0
  360. package/dist/theme/theme.js +171 -0
  361. package/dist/tree/apply.d.ts +16 -0
  362. package/dist/tree/apply.js +104 -0
  363. package/dist/tree/builders.d.ts +19 -0
  364. package/dist/tree/builders.js +20 -0
  365. package/dist/tree/compare.d.ts +68 -0
  366. package/dist/tree/compare.js +75 -0
  367. package/dist/tree/configuration.d.ts +25 -0
  368. package/dist/tree/configuration.js +108 -0
  369. package/dist/tree/delta.d.ts +288 -0
  370. package/dist/tree/delta.js +88 -0
  371. package/dist/tree/errors.d.ts +69 -0
  372. package/dist/tree/errors.js +34 -0
  373. package/dist/tree/identity.d.ts +117 -0
  374. package/dist/tree/identity.js +145 -0
  375. package/dist/tree/index.d.ts +21 -0
  376. package/dist/tree/index.js +21 -0
  377. package/dist/tree/inverse.d.ts +24 -0
  378. package/dist/tree/inverse.js +112 -0
  379. package/dist/tree/mutation.d.ts +18 -0
  380. package/dist/tree/mutation.js +49 -0
  381. package/dist/tree/naming.d.ts +4 -0
  382. package/dist/tree/naming.js +35 -0
  383. package/dist/tree/navigation.d.ts +38 -0
  384. package/dist/tree/navigation.js +83 -0
  385. package/dist/tree/node.d.ts +103 -0
  386. package/dist/tree/node.js +46 -0
  387. package/dist/tree/outline.d.ts +28 -0
  388. package/dist/tree/outline.js +10 -0
  389. package/dist/tree/tree.d.ts +83 -0
  390. package/dist/tree/tree.js +62 -0
  391. package/dist/write/commit.d.ts +124 -0
  392. package/dist/write/commit.js +234 -0
  393. package/dist/write/held.d.ts +674 -0
  394. package/dist/write/held.js +185 -0
  395. package/dist/write/index.d.ts +11 -0
  396. package/dist/write/index.js +11 -0
  397. package/dist/write/liveness.d.ts +132 -0
  398. package/dist/write/liveness.js +91 -0
  399. package/dist/write/revert.d.ts +79 -0
  400. package/dist/write/revert.js +134 -0
  401. package/package.json +160 -0
@@ -0,0 +1,70 @@
1
+ import { err, ok } from "../result.js";
2
+ import { parseReaderSignalBatch } from "./signal.js";
3
+ /**
4
+ * The doorway a browser's batches come through.
5
+ *
6
+ * A page is not a trusted author. Everything that arrives here is parsed before
7
+ * it is kept — the shape, the kinds, the tree id's grammar, and the view key's
8
+ * thirty-two characters of nothing — because the alternative is a database
9
+ * column a visitor can write anything into, including the visitor id that 0146
10
+ * exists to refuse.
11
+ *
12
+ * The route handler that serves this is a surface's, not the framework's. What
13
+ * the framework owns is this function: unknown in, a counted outcome or a
14
+ * typed refusal out, no throw either way.
15
+ */
16
+ /**
17
+ * How many batches one delivery may carry.
18
+ *
19
+ * A broadcaster sends one at a time, so anything above a handful is a retry
20
+ * queue draining after an outage, and that is worth allowing. What it is not
21
+ * worth is unbounded: the parse is the expensive part and an endpoint that will
22
+ * parse as many batches as a body can hold is an endpoint that can be made to
23
+ * spend a minute on one request.
24
+ */
25
+ export const MAX_BATCHES_PER_DELIVERY = 50;
26
+ export const describeIngestError = (error) => {
27
+ if (error.code === "too-many") {
28
+ return `a delivery may carry ${error.limit} batches and this one carried ${error.given}`;
29
+ }
30
+ if (error.code === "unavailable")
31
+ return `reader signals are unavailable: ${error.detail}`;
32
+ const first = error.issues.at(0);
33
+ return `batch ${error.index} is not a reader signal batch${first === undefined ? "" : `: ${first.path} ${first.message}`}`;
34
+ };
35
+ /**
36
+ * One batch or a list of them, because both are what senders send:
37
+ * `navigator.sendBeacon` posts a single batch and a queue draining after an
38
+ * outage posts what it has. Distinguishing them at the door costs one check and
39
+ * saves every caller an envelope.
40
+ */
41
+ const deliveryOf = (input) => (Array.isArray(input) ? input : [input]);
42
+ /**
43
+ * Parse a delivery and keep it.
44
+ *
45
+ * **Nothing is kept unless all of it parses.** A partial accept would mean a
46
+ * sender's retry either duplicates what was taken or drops what was not, and
47
+ * neither is something a browser can be asked to work out. It also means the
48
+ * refusal is actionable: one index, one reason.
49
+ */
50
+ export const ingestReaderSignals = async (journal, input) => {
51
+ const delivery = deliveryOf(input);
52
+ if (delivery.length > MAX_BATCHES_PER_DELIVERY) {
53
+ return err({ code: "too-many", limit: MAX_BATCHES_PER_DELIVERY, given: delivery.length });
54
+ }
55
+ const batches = [];
56
+ for (const [index, raw] of delivery.entries()) {
57
+ const parsed = parseReaderSignalBatch(raw);
58
+ if (!parsed.ok)
59
+ return err({ code: "invalid-delivery", index, issues: parsed.error.issues });
60
+ batches.push(parsed.value);
61
+ }
62
+ const received = await journal.receive(batches);
63
+ if (!received.ok)
64
+ return err(received.error);
65
+ return ok({
66
+ batches: batches.length,
67
+ signals: batches.reduce((count, batch) => count + batch.signals.length, 0),
68
+ });
69
+ };
70
+ //# sourceMappingURL=ingest.js.map
@@ -0,0 +1,149 @@
1
+ /**
2
+ * Who may post a batch, and how often.
3
+ *
4
+ * `ingest.ts` is the doorway a batch comes through and it asks one question:
5
+ * *is this a reader signal batch*. This module asks the other one, which no
6
+ * other part of Loom has ever had to ask — **is this deployment willing to pay
7
+ * for the answer.**
8
+ *
9
+ * Every other write in this runtime is made by a deployment's own server. A
10
+ * reader-signal batch is written by any browser that can reach the URL, and the
11
+ * table it lands in is the largest one a deployment with signals switched on
12
+ * will have. So the door needs arithmetic, and the arithmetic needs to be
13
+ * somewhere it can be read and tested without a request, a clock or a database
14
+ * — which is here, exactly as `throttle.ts` is that for the sign-in form.
15
+ *
16
+ * **No HTTP in this file.** Which status code each refusal deserves is the
17
+ * route handler's, for `ingest.ts`'s reason: the handler that serves this is a
18
+ * surface's, not the framework's.
19
+ *
20
+ * **What a subject is, is the caller's to decide, and it may not be an
21
+ * identity.** This module takes an opaque string and counts against it. 0146
22
+ * refuses anything that identifies a reader, and a limiter that had to be told
23
+ * who somebody is would be the loophole in it — so the contract is a key, and
24
+ * the caller is expected to hand over something that stops being meaningful the
25
+ * moment the counter holding it does.
26
+ */
27
+ /**
28
+ * A subject the gate could not make room for.
29
+ *
30
+ * The counter is bounded, so at some number of distinct callers it stops
31
+ * distinguishing them, and the question is what it does then. Falling open
32
+ * would mean a limiter any attacker with enough addresses can switch off, which
33
+ * is worse than none because the deployment believes it has one. Refusing
34
+ * everybody takes the site down over a crowd.
35
+ *
36
+ * So they share a count, which is `subject.ts`'s answer to the same question
37
+ * and the direction to be wrong in: stricter than counting them separately,
38
+ * and it costs nothing to a deployment that never fills the map.
39
+ */
40
+ export declare const CROWDED_SUBJECT = "crowded";
41
+ export type IntakePolicy = {
42
+ /** The largest delivery the door will read, in bytes. */
43
+ readonly maxBytes: number;
44
+ /** Deliveries one subject may make inside a window. */
45
+ readonly deliveries: number;
46
+ readonly windowMs: number;
47
+ /** How many subjects the counter distinguishes before {@link CROWDED_SUBJECT}. */
48
+ readonly subjects: number;
49
+ };
50
+ /**
51
+ * `sendBeacon` is specified to refuse a body over 64 KB, so a delivery larger
52
+ * than that did not come from a beacon — which makes the ceiling a statement
53
+ * about the sender rather than a number somebody liked. `fetch` has no such
54
+ * limit and the fallback path is held to the same one deliberately.
55
+ *
56
+ * A broadcaster flushes every five seconds, so one page view is twelve
57
+ * deliveries a minute. A hundred and twenty is eight of those at once — more
58
+ * tabs than a reader has open on one site, and enough headroom for a queue
59
+ * draining after an outage, which is the case `MAX_BATCHES_PER_DELIVERY` exists
60
+ * to allow rather than to punish.
61
+ *
62
+ * Ten thousand subjects is about a megabyte of counters and far past the point
63
+ * where the traffic is an attack rather than an audience.
64
+ */
65
+ export declare const DEFAULT_INTAKE_POLICY: IntakePolicy;
66
+ /**
67
+ * What the gate remembers about one subject: a fixed window and a count inside
68
+ * it. Two numbers and no identity, for `AttemptRecord`'s reason.
69
+ *
70
+ * A fixed window rather than a sliding one or a bucket, because the thing being
71
+ * protected is a table's growth rate over minutes and every refinement costs
72
+ * per-subject state that has to be held in memory for every caller. A caller
73
+ * who times their deliveries across a window boundary gets two windows' worth
74
+ * in a moment; at these numbers that is 240 deliveries and not a problem worth
75
+ * a data structure.
76
+ */
77
+ export type IntakeCount = {
78
+ readonly deliveries: number;
79
+ readonly windowStartedAt: number;
80
+ };
81
+ /**
82
+ * `too-large` carries the count as `admitted` does, because it spent one: a
83
+ * caller whose body was refused has still had their delivery read far enough to
84
+ * refuse it. `too-often` carries none — the count that refused them is already
85
+ * what there is to remember.
86
+ */
87
+ export type IntakeVerdict = {
88
+ readonly code: "admitted";
89
+ readonly count: IntakeCount;
90
+ } | {
91
+ readonly code: "too-large";
92
+ readonly count: IntakeCount;
93
+ readonly limit: number;
94
+ readonly given: number;
95
+ } | {
96
+ readonly code: "too-often";
97
+ readonly limit: number;
98
+ readonly retryAfterMs: number;
99
+ };
100
+ export declare const describeIntakeVerdict: (verdict: IntakeVerdict) => string;
101
+ /**
102
+ * Whether this delivery is allowed, given what the subject has already sent.
103
+ *
104
+ * Pure: no clock, no map, no request. `now` and the byte count are handed in,
105
+ * and the answer is a verdict and the count to remember.
106
+ *
107
+ * **The rate is decided before the size.** A caller already over their budget
108
+ * is told so rather than told their body was too big, because the first is the
109
+ * one they can act on and the second would restart their guessing. And an
110
+ * oversized delivery still **spends budget** — a refusal that cost the sender
111
+ * nothing is an endpoint that can be hammered for free.
112
+ *
113
+ * A `now` or a `bytes` that is not a finite number is treated as a fresh window
114
+ * and an unmeasurable body rather than trusted into the arithmetic: both arrive
115
+ * from outside — one from a clock, one from a header a caller wrote.
116
+ */
117
+ export declare const admit: (count: IntakeCount | null, bytes: number, now: number, policy: IntakePolicy) => IntakeVerdict;
118
+ export type IntakeGate = {
119
+ /**
120
+ * The policy this gate counts by.
121
+ *
122
+ * Carried on the gate rather than left beside it, because a caller holding
123
+ * both had two copies that could disagree — and the one that decides is
124
+ * whichever the gate was built with, silently. A door has one policy.
125
+ */
126
+ readonly policy: IntakePolicy;
127
+ readonly admit: (subject: string, bytes: number, now: number) => IntakeVerdict;
128
+ /** How many subjects are being counted. For a status endpoint, not for a decision. */
129
+ readonly subjects: () => number;
130
+ };
131
+ /**
132
+ * The counter that `admit` decides against.
133
+ *
134
+ * Its state is held inside the closure and changed in place, which is
135
+ * `createSignalLedger`'s arrangement and is here for the same reason: one
136
+ * process's private accumulator, reached by nothing else, constant time per
137
+ * call.
138
+ *
139
+ * **It is memory, and memory on a serverless host is per instance.** A
140
+ * deployment running eight instances tolerates roughly eight times the rate
141
+ * this policy names. That is the same caveat `attempt-log.ts` states about the
142
+ * sign-in throttle, and the answer is the same: a durable counter would mean a
143
+ * database write to decide whether to allow a database write, which is the
144
+ * cost this exists to bound. What must not happen is the limit silently
145
+ * ceasing to apply, and a bounded map that shares a count when it is full is
146
+ * how that is avoided.
147
+ */
148
+ export declare const createIntakeGate: (policy?: IntakePolicy) => IntakeGate;
149
+ //# sourceMappingURL=intake.d.ts.map
@@ -0,0 +1,154 @@
1
+ /**
2
+ * Who may post a batch, and how often.
3
+ *
4
+ * `ingest.ts` is the doorway a batch comes through and it asks one question:
5
+ * *is this a reader signal batch*. This module asks the other one, which no
6
+ * other part of Loom has ever had to ask — **is this deployment willing to pay
7
+ * for the answer.**
8
+ *
9
+ * Every other write in this runtime is made by a deployment's own server. A
10
+ * reader-signal batch is written by any browser that can reach the URL, and the
11
+ * table it lands in is the largest one a deployment with signals switched on
12
+ * will have. So the door needs arithmetic, and the arithmetic needs to be
13
+ * somewhere it can be read and tested without a request, a clock or a database
14
+ * — which is here, exactly as `throttle.ts` is that for the sign-in form.
15
+ *
16
+ * **No HTTP in this file.** Which status code each refusal deserves is the
17
+ * route handler's, for `ingest.ts`'s reason: the handler that serves this is a
18
+ * surface's, not the framework's.
19
+ *
20
+ * **What a subject is, is the caller's to decide, and it may not be an
21
+ * identity.** This module takes an opaque string and counts against it. 0146
22
+ * refuses anything that identifies a reader, and a limiter that had to be told
23
+ * who somebody is would be the loophole in it — so the contract is a key, and
24
+ * the caller is expected to hand over something that stops being meaningful the
25
+ * moment the counter holding it does.
26
+ */
27
+ /**
28
+ * A subject the gate could not make room for.
29
+ *
30
+ * The counter is bounded, so at some number of distinct callers it stops
31
+ * distinguishing them, and the question is what it does then. Falling open
32
+ * would mean a limiter any attacker with enough addresses can switch off, which
33
+ * is worse than none because the deployment believes it has one. Refusing
34
+ * everybody takes the site down over a crowd.
35
+ *
36
+ * So they share a count, which is `subject.ts`'s answer to the same question
37
+ * and the direction to be wrong in: stricter than counting them separately,
38
+ * and it costs nothing to a deployment that never fills the map.
39
+ */
40
+ export const CROWDED_SUBJECT = "crowded";
41
+ /**
42
+ * `sendBeacon` is specified to refuse a body over 64 KB, so a delivery larger
43
+ * than that did not come from a beacon — which makes the ceiling a statement
44
+ * about the sender rather than a number somebody liked. `fetch` has no such
45
+ * limit and the fallback path is held to the same one deliberately.
46
+ *
47
+ * A broadcaster flushes every five seconds, so one page view is twelve
48
+ * deliveries a minute. A hundred and twenty is eight of those at once — more
49
+ * tabs than a reader has open on one site, and enough headroom for a queue
50
+ * draining after an outage, which is the case `MAX_BATCHES_PER_DELIVERY` exists
51
+ * to allow rather than to punish.
52
+ *
53
+ * Ten thousand subjects is about a megabyte of counters and far past the point
54
+ * where the traffic is an attack rather than an audience.
55
+ */
56
+ export const DEFAULT_INTAKE_POLICY = {
57
+ maxBytes: 64 * 1024,
58
+ deliveries: 120,
59
+ windowMs: 60 * 1000,
60
+ subjects: 10_000,
61
+ };
62
+ export const describeIntakeVerdict = (verdict) => {
63
+ if (verdict.code === "admitted")
64
+ return "admitted";
65
+ if (verdict.code === "too-large") {
66
+ return `a delivery may be ${verdict.limit} bytes and this one was ${verdict.given}`;
67
+ }
68
+ return `a sender may deliver ${verdict.limit} times a window and this one has; ${verdict.retryAfterMs}ms left`;
69
+ };
70
+ const freshWindow = (now) => ({ deliveries: 1, windowStartedAt: now });
71
+ /**
72
+ * Whether this delivery is allowed, given what the subject has already sent.
73
+ *
74
+ * Pure: no clock, no map, no request. `now` and the byte count are handed in,
75
+ * and the answer is a verdict and the count to remember.
76
+ *
77
+ * **The rate is decided before the size.** A caller already over their budget
78
+ * is told so rather than told their body was too big, because the first is the
79
+ * one they can act on and the second would restart their guessing. And an
80
+ * oversized delivery still **spends budget** — a refusal that cost the sender
81
+ * nothing is an endpoint that can be hammered for free.
82
+ *
83
+ * A `now` or a `bytes` that is not a finite number is treated as a fresh window
84
+ * and an unmeasurable body rather than trusted into the arithmetic: both arrive
85
+ * from outside — one from a clock, one from a header a caller wrote.
86
+ */
87
+ export const admit = (count, bytes, now, policy) => {
88
+ const at = Number.isFinite(now) ? now : 0;
89
+ const expired = count === null || at - count.windowStartedAt >= policy.windowMs || at < count.windowStartedAt;
90
+ if (!expired && count.deliveries >= policy.deliveries) {
91
+ return {
92
+ code: "too-often",
93
+ limit: policy.deliveries,
94
+ retryAfterMs: Math.max(0, count.windowStartedAt + policy.windowMs - at),
95
+ };
96
+ }
97
+ const spent = expired
98
+ ? freshWindow(at)
99
+ : { deliveries: count.deliveries + 1, windowStartedAt: count.windowStartedAt };
100
+ /**
101
+ * An unmeasurable body is refused rather than admitted. The only caller that
102
+ * cannot say how large its delivery is, is one that chose not to.
103
+ */
104
+ const given = Number.isFinite(bytes) && bytes >= 0 ? bytes : Number.POSITIVE_INFINITY;
105
+ if (given > policy.maxBytes) {
106
+ return { code: "too-large", count: spent, limit: policy.maxBytes, given };
107
+ }
108
+ return { code: "admitted", count: spent };
109
+ };
110
+ /**
111
+ * The counter that `admit` decides against.
112
+ *
113
+ * Its state is held inside the closure and changed in place, which is
114
+ * `createSignalLedger`'s arrangement and is here for the same reason: one
115
+ * process's private accumulator, reached by nothing else, constant time per
116
+ * call.
117
+ *
118
+ * **It is memory, and memory on a serverless host is per instance.** A
119
+ * deployment running eight instances tolerates roughly eight times the rate
120
+ * this policy names. That is the same caveat `attempt-log.ts` states about the
121
+ * sign-in throttle, and the answer is the same: a durable counter would mean a
122
+ * database write to decide whether to allow a database write, which is the
123
+ * cost this exists to bound. What must not happen is the limit silently
124
+ * ceasing to apply, and a bounded map that shares a count when it is full is
125
+ * how that is avoided.
126
+ */
127
+ export const createIntakeGate = (policy = DEFAULT_INTAKE_POLICY) => {
128
+ const counts = new Map();
129
+ /** Windows that have closed hold nothing anybody is owed, so they are the first to go. */
130
+ const sweep = (now) => {
131
+ for (const [key, count] of counts) {
132
+ if (now - count.windowStartedAt >= policy.windowMs)
133
+ counts.delete(key);
134
+ }
135
+ };
136
+ const keyFor = (subject, now) => {
137
+ if (counts.has(subject) || counts.size < policy.subjects)
138
+ return subject;
139
+ sweep(now);
140
+ return counts.size < policy.subjects ? subject : CROWDED_SUBJECT;
141
+ };
142
+ return {
143
+ policy,
144
+ admit: (subject, bytes, now) => {
145
+ const key = keyFor(subject, now);
146
+ const verdict = admit(counts.get(key) ?? null, bytes, now, policy);
147
+ if (verdict.code !== "too-often")
148
+ counts.set(key, verdict.count);
149
+ return verdict;
150
+ },
151
+ subjects: () => counts.size,
152
+ };
153
+ };
154
+ //# sourceMappingURL=intake.js.map
@@ -0,0 +1,94 @@
1
+ import type { TreeId } from "../ids.js";
2
+ import { type PageDirection, type PageEnds } from "../paging.js";
3
+ import type { Result } from "../result.js";
4
+ import type { ReaderSignalBatch } from "./signal.js";
5
+ /**
6
+ * Where batches wait to be rolled up.
7
+ *
8
+ * This is a **buffer, not an archive**, and everything about it follows from
9
+ * that. Aggregates are the durable artefact (0146); raw batches exist for as
10
+ * long as it takes rollup to read them and no longer. A deployment that kept
11
+ * them would hold the largest table in its database in order to answer
12
+ * questions that are all about counters.
13
+ *
14
+ * It is deliberately the same shape as `src/telemetry/journal.ts` — append,
15
+ * page by an opaque cursor, forget a prefix — because a second paged log that
16
+ * paged differently would be a second thing to learn and a second place for the
17
+ * cursor rules to be subtly wrong. What it is not is the same *table*: a
18
+ * journal holds what the runtime said about itself, and this holds what
19
+ * browsers said about pages, and the two have different retention and different
20
+ * volumes by two orders of magnitude.
21
+ */
22
+ /**
23
+ * The only way it fails. No `not-found` — reading a tree nothing has been
24
+ * received about is an empty page, because a buffer makes no claim that a tree
25
+ * exists. No conflict — receiving a batch cannot collide with another batch.
26
+ */
27
+ export type ReaderSignalStoreError = {
28
+ readonly code: "unavailable";
29
+ readonly detail: string;
30
+ };
31
+ export declare const describeReaderSignalStoreError: (error: ReaderSignalStoreError) => string;
32
+ /**
33
+ * A batch as it comes back out, with the position the buffer gave it.
34
+ *
35
+ * `seq` orders by arrival, not by `sentAt`. A browser's clock is not merely
36
+ * skewed but attacker-controlled — `sentAt` is a number a page said — so it can
37
+ * order nothing and can certainly not be what retention measures. `receivedAt`
38
+ * is stamped here and is the only timestamp the buffer vouches for.
39
+ */
40
+ export type ReceivedBatch = ReaderSignalBatch & {
41
+ readonly seq: number;
42
+ readonly receivedAt: string;
43
+ };
44
+ export type ReaderSignalReadRequest = {
45
+ /** Absent reads every tree the handle can see, which is the scope rule (0020). */
46
+ readonly treeId?: TreeId;
47
+ /** A cursor from a previous page's `older`/`newer`, passed back unread. */
48
+ readonly cursor?: string;
49
+ /** Default `newer`, which with no cursor is the oldest page — where rollup starts. */
50
+ readonly direction?: PageDirection;
51
+ readonly limit?: number;
52
+ };
53
+ export type ReaderSignalPage = PageEnds & {
54
+ /** Always ascending by `seq`, whichever end the page was taken from. */
55
+ readonly batches: readonly ReceivedBatch[];
56
+ };
57
+ /**
58
+ * Larger than a telemetry page, because these are read only to be folded and a
59
+ * batch is small. Rollup walks the whole window, so the page size is purely how
60
+ * much of it is in memory at once.
61
+ */
62
+ export declare const DEFAULT_READER_SIGNAL_LIMIT = 500;
63
+ export declare const MAX_READER_SIGNAL_LIMIT = 2000;
64
+ export declare const clampReaderSignalLimit: (limit: number | undefined) => number;
65
+ /**
66
+ * What the buffer is asked to forget, as a position rather than a rule.
67
+ *
68
+ * Declared here rather than shared with telemetry's identical pair on purpose.
69
+ * They are the same two fields today and they answer to different policies —
70
+ * telemetry must not cut an episode in half, and this must not forget a batch
71
+ * that has not been rolled up — so a shared type would be two subsystems
72
+ * agreeing by coincidence and discovering it when one of them changes.
73
+ */
74
+ export type ForgetBefore = {
75
+ readonly before: number;
76
+ };
77
+ export type ForgetOutcome = {
78
+ readonly removed: number;
79
+ };
80
+ /**
81
+ * Three operations, mirroring the journal's.
82
+ *
83
+ * `receive` takes several batches because an ingestion endpoint may be handed
84
+ * several and should pay for one round trip. Unlike a journal's, this batch has
85
+ * no atomicity to protect — signals are independent observations and half of
86
+ * them is a smaller sample rather than a broken story — but a single statement
87
+ * is how both implementations write anyway.
88
+ */
89
+ export interface ReaderSignalJournal {
90
+ readonly receive: (batches: readonly ReaderSignalBatch[]) => Promise<Result<void, ReaderSignalStoreError>>;
91
+ readonly read: (request?: ReaderSignalReadRequest) => Promise<Result<ReaderSignalPage, ReaderSignalStoreError>>;
92
+ readonly forget: (request: ForgetBefore) => Promise<Result<ForgetOutcome, ReaderSignalStoreError>>;
93
+ }
94
+ //# sourceMappingURL=journal.d.ts.map
@@ -0,0 +1,11 @@
1
+ import { clampLimit } from "../paging.js";
2
+ export const describeReaderSignalStoreError = (error) => `reader signals are unavailable: ${error.detail}`;
3
+ /**
4
+ * Larger than a telemetry page, because these are read only to be folded and a
5
+ * batch is small. Rollup walks the whole window, so the page size is purely how
6
+ * much of it is in memory at once.
7
+ */
8
+ export const DEFAULT_READER_SIGNAL_LIMIT = 500;
9
+ export const MAX_READER_SIGNAL_LIMIT = 2000;
10
+ export const clampReaderSignalLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_READER_SIGNAL_LIMIT, max: MAX_READER_SIGNAL_LIMIT });
11
+ //# sourceMappingURL=journal.js.map
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The four kinds of reader signal, with nothing else in the module.
3
+ *
4
+ * The schema in `signal.ts` is built from this list. It lives apart so the
5
+ * broadcaster, which runs in a visitor's browser, can know the kinds without
6
+ * pulling in the schema library (0136).
7
+ */
8
+ export declare const READER_SIGNAL_KINDS: readonly ["viewed", "dwelled", "activated", "disclosed"];
9
+ /**
10
+ * The kinds whose node is not the thing a reader aimed at.
11
+ *
12
+ * A reader presses a button and opens a disclosure; both are addressed nodes of
13
+ * their own, so the node such a signal is filed against is the control rather
14
+ * than the region the control is in. `viewed` and `dwelled` have no such gap —
15
+ * they are observed on the addressed element itself — which is why these two
16
+ * carry an ancestry and the other two do not.
17
+ *
18
+ * Here rather than in `signal.ts` so the broadcaster can know which signals it
19
+ * must walk for without loading the schema library (0136).
20
+ */
21
+ export declare const DELEGATED_READER_SIGNAL_KINDS: readonly ["activated", "disclosed"];
22
+ //# sourceMappingURL=kinds.d.ts.map
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The four kinds of reader signal, with nothing else in the module.
3
+ *
4
+ * The schema in `signal.ts` is built from this list. It lives apart so the
5
+ * broadcaster, which runs in a visitor's browser, can know the kinds without
6
+ * pulling in the schema library (0136).
7
+ */
8
+ export const READER_SIGNAL_KINDS = ["viewed", "dwelled", "activated", "disclosed"];
9
+ /**
10
+ * The kinds whose node is not the thing a reader aimed at.
11
+ *
12
+ * A reader presses a button and opens a disclosure; both are addressed nodes of
13
+ * their own, so the node such a signal is filed against is the control rather
14
+ * than the region the control is in. `viewed` and `dwelled` have no such gap —
15
+ * they are observed on the addressed element itself — which is why these two
16
+ * carry an ancestry and the other two do not.
17
+ *
18
+ * Here rather than in `signal.ts` so the broadcaster can know which signals it
19
+ * must walk for without loading the schema library (0136).
20
+ */
21
+ export const DELEGATED_READER_SIGNAL_KINDS = ["activated", "disclosed"];
22
+ //# sourceMappingURL=kinds.js.map
@@ -0,0 +1,46 @@
1
+ import type { NodeId } from "../ids.js";
2
+ import type { PrimitiveType } from "../primitive-type.js";
3
+ import type { ReaderSignal } from "./signal.js";
4
+ /**
5
+ * The bookkeeping behind a broadcast, with no browser in it.
6
+ *
7
+ * Everything the broadcaster observes arrives here as a plain call with a
8
+ * timestamp — this node came on screen, that one left, the tab was hidden — and
9
+ * everything it sends leaves as the signals `drain` returns. Keeping the
10
+ * arithmetic out of the DOM code is what lets the one part that can be wrong in
11
+ * a subtle way (time counted twice, or counted while nobody was looking) be
12
+ * tested exactly.
13
+ *
14
+ * **Its state is held inside the ledger and changed in place.** A ledger that
15
+ * returned a fresh copy on every call was the first version, and it cost the
16
+ * square of the page: every node seen for the first time copied the set of every
17
+ * node seen before it, so scrolling a 6,000-node page took twelve times as long
18
+ * as a 1,000-node one rather than six. A ledger is one broadcaster's private
19
+ * accumulator, reached by nothing else, which is the same shape
20
+ * `collectTelemetry` holds its buffer in — the state is contained, and every
21
+ * call is constant time.
22
+ */
23
+ export type SignalAddress = {
24
+ readonly nodeId: NodeId;
25
+ readonly type: PrimitiveType;
26
+ };
27
+ export type SignalLedger = {
28
+ /** A node came into view. The first time it is seen while the page is visible, it is also `viewed`. */
29
+ readonly entered: (address: SignalAddress, now: number) => void;
30
+ readonly left: (nodeId: NodeId, now: number) => void;
31
+ /** Something a reader did, queued as it happened. */
32
+ readonly noted: (signal: ReaderSignal) => void;
33
+ /** The page stopped being looked at. Open stretches close; the nodes stay on screen. */
34
+ readonly hid: (now: number) => void;
35
+ /** The page is looked at again. What is on screen starts counting, and is viewed if it never was. */
36
+ readonly showed: (now: number) => void;
37
+ /**
38
+ * Everything owed since the last drain. Open stretches are cut at `now` and
39
+ * restarted from it, so a node that stays on screen across many batches is
40
+ * counted once per millisecond, in whichever batch that millisecond fell.
41
+ * Sub-millisecond remainders are dropped: a `dwelled` must be a whole number.
42
+ */
43
+ readonly drain: (now: number) => readonly ReaderSignal[];
44
+ };
45
+ export declare const createSignalLedger: (hiddenAtStart?: boolean) => SignalLedger;
46
+ //# sourceMappingURL=ledger.d.ts.map
@@ -0,0 +1,81 @@
1
+ export const createSignalLedger = (hiddenAtStart = false) => {
2
+ const onScreen = new Map();
3
+ const seen = new Set();
4
+ const dwell = new Map();
5
+ let queued = [];
6
+ let hidden = hiddenAtStart;
7
+ const accrue = (entry, now) => {
8
+ if (entry.since === null || now <= entry.since)
9
+ return;
10
+ const total = dwell.get(entry.address.nodeId);
11
+ if (total === undefined)
12
+ dwell.set(entry.address.nodeId, { address: entry.address, ms: now - entry.since });
13
+ else
14
+ total.ms += now - entry.since;
15
+ };
16
+ /** Only ever while visible: a node on screen in a tab nobody is looking at has not been viewed. */
17
+ const sighted = (address, now) => {
18
+ if (seen.has(address.nodeId))
19
+ return;
20
+ seen.add(address.nodeId);
21
+ queued.push({ kind: "viewed", ...address, at: now });
22
+ };
23
+ return {
24
+ entered: (address, now) => {
25
+ if (onScreen.has(address.nodeId))
26
+ return;
27
+ onScreen.set(address.nodeId, { address, since: hidden ? null : now });
28
+ if (!hidden)
29
+ sighted(address, now);
30
+ },
31
+ left: (nodeId, now) => {
32
+ const entry = onScreen.get(nodeId);
33
+ if (entry === undefined)
34
+ return;
35
+ accrue(entry, now);
36
+ onScreen.delete(nodeId);
37
+ },
38
+ noted: (signal) => {
39
+ queued.push(signal);
40
+ },
41
+ hid: (now) => {
42
+ if (hidden)
43
+ return;
44
+ hidden = true;
45
+ for (const entry of onScreen.values()) {
46
+ accrue(entry, now);
47
+ entry.since = null;
48
+ }
49
+ },
50
+ showed: (now) => {
51
+ if (!hidden)
52
+ return;
53
+ hidden = false;
54
+ for (const entry of onScreen.values()) {
55
+ entry.since = now;
56
+ sighted(entry.address, now);
57
+ }
58
+ },
59
+ drain: (now) => {
60
+ if (queued.length === 0 && dwell.size === 0 && (hidden || onScreen.size === 0))
61
+ return [];
62
+ if (!hidden) {
63
+ for (const entry of onScreen.values()) {
64
+ accrue(entry, now);
65
+ entry.since = now;
66
+ }
67
+ }
68
+ const dwelled = [];
69
+ for (const { address, ms } of dwell.values()) {
70
+ const whole = Math.floor(ms);
71
+ if (whole > 0)
72
+ dwelled.push({ kind: "dwelled", ...address, ms: whole });
73
+ }
74
+ const signals = queued.length === 0 ? dwelled : [...queued, ...dwelled];
75
+ queued = [];
76
+ dwell.clear();
77
+ return signals;
78
+ },
79
+ };
80
+ };
81
+ //# sourceMappingURL=ledger.js.map
@@ -0,0 +1,17 @@
1
+ import { type Clock } from "../runtime/events.js";
2
+ import { type ReaderSignalJournal } from "./journal.js";
3
+ import type { ReaderTallyStore } from "./tally.js";
4
+ /**
5
+ * The buffer and the counters, in the process.
6
+ *
7
+ * Like the memory journal and the memory store, these are the reference
8
+ * implementations rather than test doubles: the contract suite is written
9
+ * against what they do, and Postgres is checked against the same suite.
10
+ *
11
+ * The clock is a parameter for the reason it is one everywhere else — a
12
+ * `receivedAt` read off the wall clock makes every retention test a race
13
+ * against real time.
14
+ */
15
+ export declare const memoryReaderSignalJournal: (clock?: Clock) => ReaderSignalJournal;
16
+ export declare const memoryReaderTallyStore: () => ReaderTallyStore;
17
+ //# sourceMappingURL=memory.d.ts.map