@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,381 @@
1
+ import { z } from "zod";
2
+ import { type Result } from "../result.js";
3
+ /**
4
+ * What a published page may say about how it is being read.
5
+ *
6
+ * A reader signal is an observation about one node of one revision of one tree:
7
+ * it came into view, it stayed there this long, a reader activated a target in
8
+ * it, a reader opened or closed it. Nothing more, and deliberately so.
9
+ *
10
+ * **The vocabulary is closed.** Four kinds, for the same reason the operations on
11
+ * a tree are four and the schemes a URL may use are a list (0053): an adaptation
12
+ * is proposed from these, and a stream that may carry anything is a stream
13
+ * nothing can reason about. A kind is added here or it does not exist.
14
+ *
15
+ * **A signal carries no content.** No text a node shows, no URL a link goes to,
16
+ * no value a reader typed, nothing that identifies the reader. The tree already
17
+ * holds the content at the revision the signal names, and a record of what a
18
+ * person read is a record of that person — the rule telemetry already keeps for
19
+ * utterances (0023).
20
+ *
21
+ * **The revision is on every batch.** A signal about "the fourth section" means
22
+ * nothing once a proposal has moved it; a signal about node `n_42` at revision 3
23
+ * means exactly one thing forever (0136).
24
+ */
25
+ export { DELEGATED_READER_SIGNAL_KINDS, READER_SIGNAL_KINDS } from "./kinds.js";
26
+ export declare const readerSignalKindSchema: z.ZodEnum<["viewed", "dwelled", "activated", "disclosed"]>;
27
+ export type ReaderSignalKind = z.infer<typeof readerSignalKindSchema>;
28
+ /**
29
+ * The key that says two batches came from the same page view, and says nothing
30
+ * else (0146).
31
+ *
32
+ * Branded like an id, but deliberately not one: it is minted by a browser
33
+ * rather than an id factory, it is not stable, nothing may be addressed by it,
34
+ * and it is dropped when the raw window expires. `view.ts` holds the pattern
35
+ * and the minting, because the broadcaster needs both and cannot load this
36
+ * module.
37
+ */
38
+ export declare const viewKeySchema: z.ZodBranded<z.ZodString, "ViewKey">;
39
+ export type ViewKey = z.infer<typeof viewKeySchema>;
40
+ /**
41
+ * One addressed node, as a signal names it.
42
+ *
43
+ * The same pair `addressSchema` spreads, as a schema of its own, because an
44
+ * ancestry is a list of them.
45
+ */
46
+ export declare const signalAddressSchema: z.ZodObject<{
47
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
48
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
49
+ }, "strict", z.ZodTypeAny, {
50
+ type: string & z.BRAND<"PrimitiveType">;
51
+ nodeId: string & z.BRAND<"NodeId">;
52
+ }, {
53
+ type: string;
54
+ nodeId: string;
55
+ }>;
56
+ /**
57
+ * The four kinds.
58
+ *
59
+ * `viewed` fires once per node for the life of the page. `dwelled` is time on
60
+ * screen accumulated since the previous batch, so summing a node's `dwelled` over
61
+ * every batch is its total. `activated` is a reader using a link, button or field
62
+ * inside the node — the node named is the nearest addressed one, which in the
63
+ * starter library is usually the control itself. `disclosed` is a region opened
64
+ * or closed.
65
+ *
66
+ * Those last two are `DELEGATED_READER_SIGNAL_KINDS`: what a reader aimed at is
67
+ * a control, and the region it sits in is a question nothing else can answer
68
+ * afterwards, so they carry `within` and the other two do not.
69
+ */
70
+ export declare const readerSignalSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
71
+ at: z.ZodNumber;
72
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
73
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
74
+ kind: z.ZodLiteral<"viewed">;
75
+ }, "strict", z.ZodTypeAny, {
76
+ at: number;
77
+ type: string & z.BRAND<"PrimitiveType">;
78
+ kind: "viewed";
79
+ nodeId: string & z.BRAND<"NodeId">;
80
+ }, {
81
+ at: number;
82
+ type: string;
83
+ kind: "viewed";
84
+ nodeId: string;
85
+ }>, z.ZodObject<{
86
+ ms: z.ZodNumber;
87
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
88
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
89
+ kind: z.ZodLiteral<"dwelled">;
90
+ }, "strict", z.ZodTypeAny, {
91
+ type: string & z.BRAND<"PrimitiveType">;
92
+ kind: "dwelled";
93
+ nodeId: string & z.BRAND<"NodeId">;
94
+ ms: number;
95
+ }, {
96
+ type: string;
97
+ kind: "dwelled";
98
+ nodeId: string;
99
+ ms: number;
100
+ }>, z.ZodObject<{
101
+ at: z.ZodNumber;
102
+ within: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
103
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
104
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
105
+ }, "strict", z.ZodTypeAny, {
106
+ type: string & z.BRAND<"PrimitiveType">;
107
+ nodeId: string & z.BRAND<"NodeId">;
108
+ }, {
109
+ type: string;
110
+ nodeId: string;
111
+ }>, "many">>>;
112
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
113
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
114
+ kind: z.ZodLiteral<"activated">;
115
+ }, "strict", z.ZodTypeAny, {
116
+ at: number;
117
+ type: string & z.BRAND<"PrimitiveType">;
118
+ kind: "activated";
119
+ nodeId: string & z.BRAND<"NodeId">;
120
+ within?: readonly {
121
+ type: string & z.BRAND<"PrimitiveType">;
122
+ nodeId: string & z.BRAND<"NodeId">;
123
+ }[] | undefined;
124
+ }, {
125
+ at: number;
126
+ type: string;
127
+ kind: "activated";
128
+ nodeId: string;
129
+ within?: readonly {
130
+ type: string;
131
+ nodeId: string;
132
+ }[] | undefined;
133
+ }>, z.ZodObject<{
134
+ open: z.ZodBoolean;
135
+ at: z.ZodNumber;
136
+ within: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
137
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
138
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
139
+ }, "strict", z.ZodTypeAny, {
140
+ type: string & z.BRAND<"PrimitiveType">;
141
+ nodeId: string & z.BRAND<"NodeId">;
142
+ }, {
143
+ type: string;
144
+ nodeId: string;
145
+ }>, "many">>>;
146
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
147
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
148
+ kind: z.ZodLiteral<"disclosed">;
149
+ }, "strict", z.ZodTypeAny, {
150
+ at: number;
151
+ type: string & z.BRAND<"PrimitiveType">;
152
+ kind: "disclosed";
153
+ nodeId: string & z.BRAND<"NodeId">;
154
+ open: boolean;
155
+ within?: readonly {
156
+ type: string & z.BRAND<"PrimitiveType">;
157
+ nodeId: string & z.BRAND<"NodeId">;
158
+ }[] | undefined;
159
+ }, {
160
+ at: number;
161
+ type: string;
162
+ kind: "disclosed";
163
+ nodeId: string;
164
+ open: boolean;
165
+ within?: readonly {
166
+ type: string;
167
+ nodeId: string;
168
+ }[] | undefined;
169
+ }>]>;
170
+ export type ReaderSignal = z.infer<typeof readerSignalSchema>;
171
+ /**
172
+ * One delivery: the signals a page gathered since the last one, all about the
173
+ * same tree at the same revision.
174
+ *
175
+ * The tree and revision sit on the batch rather than on each signal because a
176
+ * rendered page is one revision of one tree — they cannot differ inside a batch,
177
+ * and a shape that let them would invite a consumer to wonder whether they had.
178
+ */
179
+ export declare const readerSignalBatchSchema: z.ZodObject<{
180
+ treeId: z.ZodBranded<z.ZodString, "TreeId">;
181
+ revision: z.ZodNumber;
182
+ sentAt: z.ZodNumber;
183
+ /**
184
+ * Which page view these signals came from, when the sender minted one.
185
+ *
186
+ * Optional because correlation is a capability rather than a requirement: a
187
+ * batch synthesised on a server, replayed from a fixture, or sent by a host
188
+ * that wants totals and no funnel has nothing to correlate, and refusing it
189
+ * would make the funnel mandatory rather than available. Rollup counts the
190
+ * batches it could not correlate instead of quietly treating each as its own
191
+ * view, which would inflate every funnel denominator.
192
+ */
193
+ view: z.ZodOptional<z.ZodBranded<z.ZodString, "ViewKey">>;
194
+ signals: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
195
+ at: z.ZodNumber;
196
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
197
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
198
+ kind: z.ZodLiteral<"viewed">;
199
+ }, "strict", z.ZodTypeAny, {
200
+ at: number;
201
+ type: string & z.BRAND<"PrimitiveType">;
202
+ kind: "viewed";
203
+ nodeId: string & z.BRAND<"NodeId">;
204
+ }, {
205
+ at: number;
206
+ type: string;
207
+ kind: "viewed";
208
+ nodeId: string;
209
+ }>, z.ZodObject<{
210
+ ms: z.ZodNumber;
211
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
212
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
213
+ kind: z.ZodLiteral<"dwelled">;
214
+ }, "strict", z.ZodTypeAny, {
215
+ type: string & z.BRAND<"PrimitiveType">;
216
+ kind: "dwelled";
217
+ nodeId: string & z.BRAND<"NodeId">;
218
+ ms: number;
219
+ }, {
220
+ type: string;
221
+ kind: "dwelled";
222
+ nodeId: string;
223
+ ms: number;
224
+ }>, z.ZodObject<{
225
+ at: z.ZodNumber;
226
+ within: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
227
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
228
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
229
+ }, "strict", z.ZodTypeAny, {
230
+ type: string & z.BRAND<"PrimitiveType">;
231
+ nodeId: string & z.BRAND<"NodeId">;
232
+ }, {
233
+ type: string;
234
+ nodeId: string;
235
+ }>, "many">>>;
236
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
237
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
238
+ kind: z.ZodLiteral<"activated">;
239
+ }, "strict", z.ZodTypeAny, {
240
+ at: number;
241
+ type: string & z.BRAND<"PrimitiveType">;
242
+ kind: "activated";
243
+ nodeId: string & z.BRAND<"NodeId">;
244
+ within?: readonly {
245
+ type: string & z.BRAND<"PrimitiveType">;
246
+ nodeId: string & z.BRAND<"NodeId">;
247
+ }[] | undefined;
248
+ }, {
249
+ at: number;
250
+ type: string;
251
+ kind: "activated";
252
+ nodeId: string;
253
+ within?: readonly {
254
+ type: string;
255
+ nodeId: string;
256
+ }[] | undefined;
257
+ }>, z.ZodObject<{
258
+ open: z.ZodBoolean;
259
+ at: z.ZodNumber;
260
+ within: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
261
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
262
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
263
+ }, "strict", z.ZodTypeAny, {
264
+ type: string & z.BRAND<"PrimitiveType">;
265
+ nodeId: string & z.BRAND<"NodeId">;
266
+ }, {
267
+ type: string;
268
+ nodeId: string;
269
+ }>, "many">>>;
270
+ nodeId: z.ZodBranded<z.ZodString, "NodeId">;
271
+ type: z.ZodBranded<z.ZodString, "PrimitiveType">;
272
+ kind: z.ZodLiteral<"disclosed">;
273
+ }, "strict", z.ZodTypeAny, {
274
+ at: number;
275
+ type: string & z.BRAND<"PrimitiveType">;
276
+ kind: "disclosed";
277
+ nodeId: string & z.BRAND<"NodeId">;
278
+ open: boolean;
279
+ within?: readonly {
280
+ type: string & z.BRAND<"PrimitiveType">;
281
+ nodeId: string & z.BRAND<"NodeId">;
282
+ }[] | undefined;
283
+ }, {
284
+ at: number;
285
+ type: string;
286
+ kind: "disclosed";
287
+ nodeId: string;
288
+ open: boolean;
289
+ within?: readonly {
290
+ type: string;
291
+ nodeId: string;
292
+ }[] | undefined;
293
+ }>]>, "many">;
294
+ }, "strict", z.ZodTypeAny, {
295
+ treeId: string & z.BRAND<"TreeId">;
296
+ revision: number;
297
+ sentAt: number;
298
+ signals: ({
299
+ at: number;
300
+ type: string & z.BRAND<"PrimitiveType">;
301
+ kind: "viewed";
302
+ nodeId: string & z.BRAND<"NodeId">;
303
+ } | {
304
+ type: string & z.BRAND<"PrimitiveType">;
305
+ kind: "dwelled";
306
+ nodeId: string & z.BRAND<"NodeId">;
307
+ ms: number;
308
+ } | {
309
+ at: number;
310
+ type: string & z.BRAND<"PrimitiveType">;
311
+ kind: "activated";
312
+ nodeId: string & z.BRAND<"NodeId">;
313
+ within?: readonly {
314
+ type: string & z.BRAND<"PrimitiveType">;
315
+ nodeId: string & z.BRAND<"NodeId">;
316
+ }[] | undefined;
317
+ } | {
318
+ at: number;
319
+ type: string & z.BRAND<"PrimitiveType">;
320
+ kind: "disclosed";
321
+ nodeId: string & z.BRAND<"NodeId">;
322
+ open: boolean;
323
+ within?: readonly {
324
+ type: string & z.BRAND<"PrimitiveType">;
325
+ nodeId: string & z.BRAND<"NodeId">;
326
+ }[] | undefined;
327
+ })[];
328
+ view?: (string & z.BRAND<"ViewKey">) | undefined;
329
+ }, {
330
+ treeId: string;
331
+ revision: number;
332
+ sentAt: number;
333
+ signals: ({
334
+ at: number;
335
+ type: string;
336
+ kind: "viewed";
337
+ nodeId: string;
338
+ } | {
339
+ type: string;
340
+ kind: "dwelled";
341
+ nodeId: string;
342
+ ms: number;
343
+ } | {
344
+ at: number;
345
+ type: string;
346
+ kind: "activated";
347
+ nodeId: string;
348
+ within?: readonly {
349
+ type: string;
350
+ nodeId: string;
351
+ }[] | undefined;
352
+ } | {
353
+ at: number;
354
+ type: string;
355
+ kind: "disclosed";
356
+ nodeId: string;
357
+ open: boolean;
358
+ within?: readonly {
359
+ type: string;
360
+ nodeId: string;
361
+ }[] | undefined;
362
+ })[];
363
+ view?: string | undefined;
364
+ }>;
365
+ export type ReaderSignalBatch = z.infer<typeof readerSignalBatchSchema>;
366
+ export type ReaderSignalParseError = {
367
+ readonly code: "invalid-batch";
368
+ readonly issues: readonly {
369
+ readonly path: string;
370
+ readonly message: string;
371
+ }[];
372
+ };
373
+ /**
374
+ * Read a batch that arrived from somewhere untrusted — a request body, a queue.
375
+ *
376
+ * A browser is not a trusted author, so anything that receives batches parses
377
+ * them here rather than trusting the shape. Invalid input is a value, never a
378
+ * throw.
379
+ */
380
+ export declare const parseReaderSignalBatch: (input: unknown) => Result<ReaderSignalBatch, ReaderSignalParseError>;
381
+ //# sourceMappingURL=signal.d.ts.map
@@ -0,0 +1,150 @@
1
+ import { z } from "zod";
2
+ import { nodeIdSchema, treeIdSchema } from "../ids.js";
3
+ import { primitiveTypeSchema } from "../primitive-type.js";
4
+ import { err, ok } from "../result.js";
5
+ import { READER_SIGNAL_KINDS } from "./kinds.js";
6
+ import { viewKeyPattern } from "./view.js";
7
+ /**
8
+ * What a published page may say about how it is being read.
9
+ *
10
+ * A reader signal is an observation about one node of one revision of one tree:
11
+ * it came into view, it stayed there this long, a reader activated a target in
12
+ * it, a reader opened or closed it. Nothing more, and deliberately so.
13
+ *
14
+ * **The vocabulary is closed.** Four kinds, for the same reason the operations on
15
+ * a tree are four and the schemes a URL may use are a list (0053): an adaptation
16
+ * is proposed from these, and a stream that may carry anything is a stream
17
+ * nothing can reason about. A kind is added here or it does not exist.
18
+ *
19
+ * **A signal carries no content.** No text a node shows, no URL a link goes to,
20
+ * no value a reader typed, nothing that identifies the reader. The tree already
21
+ * holds the content at the revision the signal names, and a record of what a
22
+ * person read is a record of that person — the rule telemetry already keeps for
23
+ * utterances (0023).
24
+ *
25
+ * **The revision is on every batch.** A signal about "the fourth section" means
26
+ * nothing once a proposal has moved it; a signal about node `n_42` at revision 3
27
+ * means exactly one thing forever (0136).
28
+ */
29
+ export { DELEGATED_READER_SIGNAL_KINDS, READER_SIGNAL_KINDS } from "./kinds.js";
30
+ export const readerSignalKindSchema = z.enum(READER_SIGNAL_KINDS);
31
+ const instantSchema = z.number().int().nonnegative();
32
+ /**
33
+ * The key that says two batches came from the same page view, and says nothing
34
+ * else (0146).
35
+ *
36
+ * Branded like an id, but deliberately not one: it is minted by a browser
37
+ * rather than an id factory, it is not stable, nothing may be addressed by it,
38
+ * and it is dropped when the raw window expires. `view.ts` holds the pattern
39
+ * and the minting, because the broadcaster needs both and cannot load this
40
+ * module.
41
+ */
42
+ export const viewKeySchema = z.string().regex(viewKeyPattern).brand();
43
+ const addressSchema = {
44
+ nodeId: nodeIdSchema,
45
+ type: primitiveTypeSchema,
46
+ };
47
+ /**
48
+ * One addressed node, as a signal names it.
49
+ *
50
+ * The same pair `addressSchema` spreads, as a schema of its own, because an
51
+ * ancestry is a list of them.
52
+ */
53
+ export const signalAddressSchema = z.object(addressSchema).strict();
54
+ /**
55
+ * The addressed nodes a delegated signal happened inside, nearest first.
56
+ *
57
+ * A reader presses a button, and the button is an addressed node — so the node
58
+ * an `activated` is filed against is the control, never the band the control is
59
+ * in. Without this a deployment can report *which button was pressed* and can
60
+ * never report *how many readers used something in the pricing section*, because
61
+ * no signal a browser sends carries the section.
62
+ *
63
+ * **It is ancestry, not content.** Node ids and primitive types, which the tree
64
+ * at this revision already holds. A signal still says nothing about the reader
65
+ * and nothing about what the page shows.
66
+ *
67
+ * **Optional, and absent is not empty.** A batch synthesised on a server, one
68
+ * replayed from a fixture, and one from a sender that was asked not to walk all
69
+ * have nothing to say here; a signal against a node at the root of the page has
70
+ * an empty ancestry and says so. A consumer that treats the two the same is
71
+ * treating *we did not look* as *there was nothing above it*.
72
+ */
73
+ const withinSchema = z.array(signalAddressSchema).readonly();
74
+ /**
75
+ * The four kinds.
76
+ *
77
+ * `viewed` fires once per node for the life of the page. `dwelled` is time on
78
+ * screen accumulated since the previous batch, so summing a node's `dwelled` over
79
+ * every batch is its total. `activated` is a reader using a link, button or field
80
+ * inside the node — the node named is the nearest addressed one, which in the
81
+ * starter library is usually the control itself. `disclosed` is a region opened
82
+ * or closed.
83
+ *
84
+ * Those last two are `DELEGATED_READER_SIGNAL_KINDS`: what a reader aimed at is
85
+ * a control, and the region it sits in is a question nothing else can answer
86
+ * afterwards, so they carry `within` and the other two do not.
87
+ */
88
+ export const readerSignalSchema = z.discriminatedUnion("kind", [
89
+ z.object({ kind: z.literal("viewed"), ...addressSchema, at: instantSchema }).strict(),
90
+ z.object({ kind: z.literal("dwelled"), ...addressSchema, ms: z.number().int().positive() }).strict(),
91
+ z
92
+ .object({ kind: z.literal("activated"), ...addressSchema, at: instantSchema, within: withinSchema.optional() })
93
+ .strict(),
94
+ z
95
+ .object({
96
+ kind: z.literal("disclosed"),
97
+ ...addressSchema,
98
+ open: z.boolean(),
99
+ at: instantSchema,
100
+ within: withinSchema.optional(),
101
+ })
102
+ .strict(),
103
+ ]);
104
+ /**
105
+ * One delivery: the signals a page gathered since the last one, all about the
106
+ * same tree at the same revision.
107
+ *
108
+ * The tree and revision sit on the batch rather than on each signal because a
109
+ * rendered page is one revision of one tree — they cannot differ inside a batch,
110
+ * and a shape that let them would invite a consumer to wonder whether they had.
111
+ */
112
+ export const readerSignalBatchSchema = z
113
+ .object({
114
+ treeId: treeIdSchema,
115
+ revision: z.number().int().nonnegative(),
116
+ sentAt: instantSchema,
117
+ /**
118
+ * Which page view these signals came from, when the sender minted one.
119
+ *
120
+ * Optional because correlation is a capability rather than a requirement: a
121
+ * batch synthesised on a server, replayed from a fixture, or sent by a host
122
+ * that wants totals and no funnel has nothing to correlate, and refusing it
123
+ * would make the funnel mandatory rather than available. Rollup counts the
124
+ * batches it could not correlate instead of quietly treating each as its own
125
+ * view, which would inflate every funnel denominator.
126
+ */
127
+ view: viewKeySchema.optional(),
128
+ signals: z.array(readerSignalSchema).min(1),
129
+ })
130
+ .strict();
131
+ /**
132
+ * Read a batch that arrived from somewhere untrusted — a request body, a queue.
133
+ *
134
+ * A browser is not a trusted author, so anything that receives batches parses
135
+ * them here rather than trusting the shape. Invalid input is a value, never a
136
+ * throw.
137
+ */
138
+ export const parseReaderSignalBatch = (input) => {
139
+ const parsed = readerSignalBatchSchema.safeParse(input);
140
+ return parsed.success
141
+ ? ok(parsed.data)
142
+ : err({
143
+ code: "invalid-batch",
144
+ issues: parsed.error.issues.map((issue) => ({
145
+ path: issue.path.join("."),
146
+ message: issue.message,
147
+ })),
148
+ });
149
+ };
150
+ //# sourceMappingURL=signal.js.map
@@ -0,0 +1,70 @@
1
+ import type { TreeId } from "../ids.js";
2
+ import type { Result } from "../result.js";
3
+ import type { FunnelAnswer, ReaderTally } from "./rollup.js";
4
+ import type { ReaderSignalStoreError } from "./journal.js";
5
+ /**
6
+ * Where the counters live once the batches they came from are gone.
7
+ *
8
+ * This is the durable half. The portal reads it, retention never touches it,
9
+ * and nothing in it can be traced to a reader: a tally is a node, a revision
10
+ * and six numbers.
11
+ *
12
+ * **Applying a rollup is additive, not a replacement.** Rollup runs over a
13
+ * window of the buffer and is run again over the next window, so what it
14
+ * produces is *what this window added* rather than *what is true so far*. A
15
+ * store that overwrote would silently discard every window but the last, and
16
+ * the symptom — counters that look plausible and only ever describe the last
17
+ * few minutes — is the kind nobody notices.
18
+ *
19
+ * **Except the view counts, which is the one place this is lossy and the
20
+ * reason it is written down here (0147).** `views` and `reached` count *distinct*
21
+ * views, and distinctness cannot be added up: a reader whose page view spans
22
+ * two windows is one view in each and two after the sum. The error is bounded
23
+ * by how many views straddle a window boundary, it is always an over-count, and
24
+ * the alternative is keeping view keys in durable storage — which is the thing
25
+ * 0146 refuses. A deployment that wants the bound small makes the rollup window
26
+ * long relative to a page view, which is the default.
27
+ */
28
+ /** One node's line as the store keeps it, which is a tally plus when it last changed. */
29
+ export type StoredTally = ReaderTally & {
30
+ readonly updatedAt: string;
31
+ };
32
+ /** One funnel answer as the store keeps it. */
33
+ export type StoredFunnel = FunnelAnswer & {
34
+ readonly updatedAt: string;
35
+ };
36
+ export type TallyReadRequest = {
37
+ /** Absent reads every tree the handle can see, which is the scope rule (0020). */
38
+ readonly treeId?: TreeId;
39
+ /**
40
+ * Absent reads every revision.
41
+ *
42
+ * Almost every question the portal asks is about one revision or about two
43
+ * being compared, and *before versus after a change* is the second of those —
44
+ * so this is a filter rather than a requirement, and a caller comparing
45
+ * revisions reads them all and groups.
46
+ */
47
+ readonly revision?: number;
48
+ };
49
+ /**
50
+ * Counters are not paged.
51
+ *
52
+ * A page of a log is unbounded because a log only grows; tallies are bounded by
53
+ * the nodes of the revisions a deployment has, which is the size of its trees.
54
+ * Paging them would be a cursor every caller has to carry for a result that
55
+ * fits in a response.
56
+ */
57
+ export interface ReaderTallyStore {
58
+ /**
59
+ * Add a rollup's counters to what is already there, creating rows that do not
60
+ * exist yet. Atomic over the whole rollup where the backend can be: a partly
61
+ * applied window is counters that disagree with each other.
62
+ */
63
+ readonly apply: (rollup: {
64
+ readonly tallies: readonly ReaderTally[];
65
+ readonly funnels: readonly FunnelAnswer[];
66
+ }, at: string) => Promise<Result<void, ReaderSignalStoreError>>;
67
+ readonly tallies: (request?: TallyReadRequest) => Promise<Result<readonly StoredTally[], ReaderSignalStoreError>>;
68
+ readonly funnels: (request?: TallyReadRequest) => Promise<Result<readonly StoredFunnel[], ReaderSignalStoreError>>;
69
+ }
70
+ //# sourceMappingURL=tally.d.ts.map
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=tally.js.map
@@ -0,0 +1,51 @@
1
+ import type { ViewKey } from "./signal.js";
2
+ /**
3
+ * The one value in the reader-signal seam that correlates anything.
4
+ *
5
+ * A view key is minted in the browser when a broadcast starts, rides every
6
+ * batch of that one page view, and is never seen again. It exists so a funnel
7
+ * can be answered — *of the views that reached the pricing band, how many
8
+ * pressed the button* — which per-node totals cannot answer and which is half
9
+ * of what the portal is for ([0146](../../decisions/0146-a-reader-signal-stays-anonymous-and-a-funnel-is-correlated-inside-one-page-view.md)).
10
+ *
11
+ * Everything else about it is a refusal. It is not a cookie and is not written
12
+ * to storage of any kind, so it does not survive a reload. It is not derived
13
+ * from the reader, their device, their address or their clock — it is random
14
+ * bytes and nothing else. It does not leave the aggregation step: rollup reads
15
+ * it and the counters it produces do not carry it, so it expires with the raw
16
+ * window.
17
+ *
18
+ * **The shape is strict for a reason that is not tidiness.** A free-form string
19
+ * here is an identity backdoor: a host wanting a visitor id could put one in
20
+ * this field and everything downstream would keep working. Thirty-two hex
21
+ * characters of nothing hold no room for a hash of an address, an account id,
22
+ * or a user agent, and a batch carrying one is refused at the parser rather
23
+ * than stored and noticed later.
24
+ *
25
+ * This module is loaded by the broadcaster, so it imports no package and
26
+ * touches no schema (0136). The schema built from the constants below lives in
27
+ * `signal.ts`, which a browser never loads.
28
+ */
29
+ /**
30
+ * 128 bits, the same width a UUID spends on randomness.
31
+ *
32
+ * The number that matters is not the collision probability against all views
33
+ * ever, but against the views inside one raw window on one deployment — the
34
+ * only span in which two keys are ever compared. At 128 bits that is
35
+ * unreachable, and the field costs 32 bytes on a batch that already carries
36
+ * several signals.
37
+ */
38
+ export declare const VIEW_KEY_BYTES = 16;
39
+ export declare const VIEW_KEY_LENGTH: number;
40
+ export declare const viewKeyPattern: RegExp;
41
+ /**
42
+ * Where the randomness comes from. A parameter so a test can mint a key it can
43
+ * name, and for no other reason — a host has no business supplying this.
44
+ */
45
+ export type RandomBytes = (count: number) => Uint8Array;
46
+ /**
47
+ * A fresh view key. Called once per broadcast, never per batch — the whole
48
+ * point is that the batches of one page view agree.
49
+ */
50
+ export declare const mintViewKey: (random?: RandomBytes) => ViewKey;
51
+ //# sourceMappingURL=view.d.ts.map