@jam-overture/loom 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -29,11 +29,12 @@ import type { ReadingProgress, ReadingStop } from "./progress.js";
29
29
  * does not. Ranking the raw losses therefore ranks partly by how long readers
30
30
  * stay, which is not the question anybody asked.
31
31
  *
32
- * So the ranking key is the loss put **on the scale the door counts in**:
33
- * `lost ÷ (1 + inflation)`, where the inflation is that page's own
34
- * `drift ÷ opened` off that page's own door row. The rule for picking the right
35
- * row is published beside the counter it is a rule about and is reused here
36
- * rather than written a second time
32
+ * So the ranking key is the loss put **on the scale the door counts in**, by
33
+ * `atDoorScale` off that page's own door row
34
+ * ([0265](../../decisions/0265-what-readers-do-inside-a-kind-of-part-is-a-share-of-the-readers-who-met-it-and-the-door-is-only-a-weight.md),
35
+ * [0346](../../decisions/0346-the-doors-scale-is-total-so-the-three-ranking-keys-read-the-one-rule.md)).
36
+ * The rule for picking the right row is published beside the counter it is a
37
+ * rule about and is reused here rather than written a second time
37
38
  * ([0219](../../decisions/0219-a-page-view-is-counted-once-at-the-door-and-the-over-count-in-the-node-counters-is-a-measurement.md)).
38
39
  *
39
40
  * The figure that comes out is not a count of people and is deliberately not
@@ -132,6 +133,18 @@ export type DeploymentSilence =
132
133
  */
133
134
  | "inconsistent";
134
135
  export declare const DEPLOYMENT_SILENCES: readonly DeploymentSilence[];
136
+ /**
137
+ * One line per silence, for a surface saying why a page is not in the order.
138
+ *
139
+ * **The sentences are the order's own, moved here rather than written again.**
140
+ * Every member of this set is also a {@link RankStanding}, and
141
+ * {@link describeRankStanding} has had a line for each since the order was
142
+ * built — so writing a second spelling of *nothing reported a view of this
143
+ * version* would be the overlap the census of silences exists to resolve, one
144
+ * module in. The standing defers to this for the five they share and the text
145
+ * is unchanged from what it returned.
146
+ */
147
+ export declare const describeDeploymentSilence: (silence: DeploymentSilence) => string;
135
148
  /** Where one page stands in the order, or why it is not in it. */
136
149
  export type RankStanding =
137
150
  /** In the order, with a fall and a scale for it. */
@@ -1,5 +1,6 @@
1
1
  import { everyMemberOf } from "../closed-set.js";
2
2
  import { audienceScopeRead, readingKeyOf } from "./audiences.js";
3
+ import { atDoorScale, doorOf } from "./door.js";
3
4
  import { pageViewsFor } from "./page-views.js";
4
5
  export const DEPLOYMENT_SILENCES = everyMemberOf()([
5
6
  "unread",
@@ -8,6 +9,31 @@ export const DEPLOYMENT_SILENCES = everyMemberOf()([
8
9
  "unopened",
9
10
  "inconsistent",
10
11
  ]);
12
+ /**
13
+ * One line per silence, for a surface saying why a page is not in the order.
14
+ *
15
+ * **The sentences are the order's own, moved here rather than written again.**
16
+ * Every member of this set is also a {@link RankStanding}, and
17
+ * {@link describeRankStanding} has had a line for each since the order was
18
+ * built — so writing a second spelling of *nothing reported a view of this
19
+ * version* would be the overlap the census of silences exists to resolve, one
20
+ * module in. The standing defers to this for the five they share and the text
21
+ * is unchanged from what it returned.
22
+ */
23
+ export const describeDeploymentSilence = (silence) => {
24
+ switch (silence) {
25
+ case "unread":
26
+ return "nothing reported a view of this version in the window";
27
+ case "unsplit":
28
+ return "one window holds two forms of the page and says which readers neither";
29
+ case "unscaled":
30
+ return "no page views counted at the door, so its loss is not comparable with another page's";
31
+ case "unopened":
32
+ return "the page-view row is there and nothing has said a page view began";
33
+ case "inconsistent":
34
+ return "it loses more readers at one fall than have ever appeared";
35
+ }
36
+ };
11
37
  export const RANK_STANDINGS = everyMemberOf()([
12
38
  "ranked",
13
39
  "unbroken",
@@ -24,16 +50,8 @@ export const describeRankStanding = (standing) => {
24
50
  return "in the order, by the readers it loses at its sharpest fall";
25
51
  case "unbroken":
26
52
  return "read, and losing nobody anywhere on the page";
27
- case "unread":
28
- return "nothing reported a view of this version in the window";
29
- case "unsplit":
30
- return "one window holds two forms of the page and says which readers neither";
31
- case "unscaled":
32
- return "no page views counted at the door, so its loss is not comparable with another page's";
33
- case "unopened":
34
- return "the page-view row is there and nothing has said a page view began";
35
- case "inconsistent":
36
- return "it loses more readers at one fall than have ever appeared";
53
+ default:
54
+ return describeDeploymentSilence(standing);
37
55
  }
38
56
  };
39
57
  const EMPTY_STANDINGS = Object.freeze(Object.fromEntries(RANK_STANDINGS.map((standing) => [standing, 0])));
@@ -82,12 +100,20 @@ const rowOf = (page, door) => {
82
100
  if (at.lost > door.appearances) {
83
101
  return { ...where, standing: "inconsistent", at, lost: at.lost, readers: null, share: at.share };
84
102
  }
103
+ /**
104
+ * The scale is read off the rule published beside the counter rather than
105
+ * spelled a second time here (0346). It was `at.lost ÷ (1 + door.inflation)`,
106
+ * which is the same rule arrived at by a different route — and the two routes
107
+ * do not agree in the last place, so the key moves there on a page with drift.
108
+ * Nothing orders on a sixteenth decimal and the published spelling is the
109
+ * closer of the two to the exact value, never the further.
110
+ */
85
111
  return {
86
112
  ...where,
87
113
  standing: "ranked",
88
114
  at,
89
115
  lost: at.lost,
90
- readers: at.lost / (1 + door.inflation),
116
+ readers: atDoorScale(at.lost, doorOf(door)),
91
117
  share: at.share,
92
118
  };
93
119
  };
@@ -67,16 +67,16 @@ export declare const doorOf: (row: RevisionPageViews | null) => PageDoor;
67
67
  * `count × counted ÷ appearances`: the count's own sound share of that page's
68
68
  * appearances (0229), weighted by the page views a rollup actually folded
69
69
  * (0250). It is the expression every reader-weighted figure over a library is
70
- * built out of, and until now it was **five hand-written copies of it** — one
71
- * in a kind's share of readers, two in what readers do inside a kind, two in a
72
- * comparison of the first — which is the state this module was created to end
73
- * and did not quite reach: {@link PageDoor} held the per-page half of the rule
74
- * and the per-placement half stayed at each call site.
70
+ * built out of, and it was **five hand-written copies of it** — one in a kind's
71
+ * share of readers, two in what readers do inside a kind, two in a comparison of
72
+ * the first — which is the state this module was created to end and did not
73
+ * quite reach: {@link PageDoor} held the per-page half of the rule and the
74
+ * per-placement half stayed at each call site.
75
75
  *
76
- * **The multiplication comes before the division**, which is not a style: the
77
- * three floats agree to fifteen places in either order and not to sixteen, and
78
- * 0229 has already been bitten by exactly that. Written this way the helper is
79
- * bit-identical to every copy it replaces.
76
+ * Three **ranking keys** then turned out to be the same rule written a sixth,
77
+ * seventh and eighth time as `count ÷ (1 + inflation)` — the order of
78
+ * conversions (0333), of falls (0250) and of movements (0291). All three read
79
+ * this one now (0346).
80
80
  *
81
81
  * `scaledBy` is a **second** door, for the one caller that needs one: a
82
82
  * comparison asks what one side's reading would have come to with the other
@@ -84,9 +84,31 @@ export declare const doorOf: (row: RevisionPageViews | null) => PageDoor;
84
84
  * the weight is the other's. It defaults to the door the count came from, which
85
85
  * is every other caller.
86
86
  *
87
- * Only ever called for a door with no silence, where `appearances` is
88
- * positive — a page the door cannot scale has no term in any of these figures
89
- * at all.
87
+ * **Total, and the two short-circuits are the reason three ranking keys can
88
+ * share it** (0346). It was documented as *only ever called for a door with no
89
+ * silence, where `appearances` is positive*, and that precondition is what kept
90
+ * the orders of falls and of movements writing the rule a second time by hand as
91
+ * `count ÷ (1 + inflation)` — a division-first spelling that is total where this
92
+ * one divided by nothing. Both cases are now answered here:
93
+ *
94
+ * - **A door that folded nothing has nothing to divide out.** With no
95
+ * appearances there is no scale to put the count on and no straddle in it to
96
+ * remove, so the count is its own figure. The alternative is a `NaN` in a
97
+ * ranking key, which sorts wherever the comparator leaves it.
98
+ * - **A scale that is the identity is taken exactly.** Where the weight equals
99
+ * the appearances it divides — every page with no drift, which is most of
100
+ * them — `count × n ÷ n` is the count mathematically and **not** in floats:
101
+ * `0.1 × 3 ÷ 3` is `0.10000000000000002`. A movement of a share is not a whole
102
+ * number, so a page the door has nothing to correct would have had its
103
+ * published figure moved by the correction. Returning the count says the same
104
+ * thing and says it in the last place too.
105
+ *
106
+ * **The multiplication comes before the division** otherwise, which is not a
107
+ * style: the three floats agree to fifteen places in either order and not to
108
+ * sixteen, and 0229 has already been bitten by exactly that. Over 22,100 integer
109
+ * triples where the scale is not the identity, this spelling is never further
110
+ * from the exact value than the division-first one and is strictly closer in
111
+ * 4,963 of them.
90
112
  */
91
113
  export declare const atDoorScale: (count: number, of: PageDoor, scaledBy?: PageDoor) => number;
92
114
  //# sourceMappingURL=door.d.ts.map
@@ -28,16 +28,16 @@ export const doorOf = (row) => {
28
28
  * `count × counted ÷ appearances`: the count's own sound share of that page's
29
29
  * appearances (0229), weighted by the page views a rollup actually folded
30
30
  * (0250). It is the expression every reader-weighted figure over a library is
31
- * built out of, and until now it was **five hand-written copies of it** — one
32
- * in a kind's share of readers, two in what readers do inside a kind, two in a
33
- * comparison of the first — which is the state this module was created to end
34
- * and did not quite reach: {@link PageDoor} held the per-page half of the rule
35
- * and the per-placement half stayed at each call site.
31
+ * built out of, and it was **five hand-written copies of it** — one in a kind's
32
+ * share of readers, two in what readers do inside a kind, two in a comparison of
33
+ * the first — which is the state this module was created to end and did not
34
+ * quite reach: {@link PageDoor} held the per-page half of the rule and the
35
+ * per-placement half stayed at each call site.
36
36
  *
37
- * **The multiplication comes before the division**, which is not a style: the
38
- * three floats agree to fifteen places in either order and not to sixteen, and
39
- * 0229 has already been bitten by exactly that. Written this way the helper is
40
- * bit-identical to every copy it replaces.
37
+ * Three **ranking keys** then turned out to be the same rule written a sixth,
38
+ * seventh and eighth time as `count ÷ (1 + inflation)` — the order of
39
+ * conversions (0333), of falls (0250) and of movements (0291). All three read
40
+ * this one now (0346).
41
41
  *
42
42
  * `scaledBy` is a **second** door, for the one caller that needs one: a
43
43
  * comparison asks what one side's reading would have come to with the other
@@ -45,9 +45,33 @@ export const doorOf = (row) => {
45
45
  * the weight is the other's. It defaults to the door the count came from, which
46
46
  * is every other caller.
47
47
  *
48
- * Only ever called for a door with no silence, where `appearances` is
49
- * positive — a page the door cannot scale has no term in any of these figures
50
- * at all.
48
+ * **Total, and the two short-circuits are the reason three ranking keys can
49
+ * share it** (0346). It was documented as *only ever called for a door with no
50
+ * silence, where `appearances` is positive*, and that precondition is what kept
51
+ * the orders of falls and of movements writing the rule a second time by hand as
52
+ * `count ÷ (1 + inflation)` — a division-first spelling that is total where this
53
+ * one divided by nothing. Both cases are now answered here:
54
+ *
55
+ * - **A door that folded nothing has nothing to divide out.** With no
56
+ * appearances there is no scale to put the count on and no straddle in it to
57
+ * remove, so the count is its own figure. The alternative is a `NaN` in a
58
+ * ranking key, which sorts wherever the comparator leaves it.
59
+ * - **A scale that is the identity is taken exactly.** Where the weight equals
60
+ * the appearances it divides — every page with no drift, which is most of
61
+ * them — `count × n ÷ n` is the count mathematically and **not** in floats:
62
+ * `0.1 × 3 ÷ 3` is `0.10000000000000002`. A movement of a share is not a whole
63
+ * number, so a page the door has nothing to correct would have had its
64
+ * published figure moved by the correction. Returning the count says the same
65
+ * thing and says it in the last place too.
66
+ *
67
+ * **The multiplication comes before the division** otherwise, which is not a
68
+ * style: the three floats agree to fifteen places in either order and not to
69
+ * sixteen, and 0229 has already been bitten by exactly that. Over 22,100 integer
70
+ * triples where the scale is not the identity, this spelling is never further
71
+ * from the exact value than the division-first one and is strictly closer in
72
+ * 4,963 of them.
51
73
  */
52
- export const atDoorScale = (count, of, scaledBy = of) => (count * scaledBy.counted) / of.appearances;
74
+ export const atDoorScale = (count, of, scaledBy = of) => of.appearances === 0 || scaledBy.counted === of.appearances
75
+ ? count
76
+ : (count * scaledBy.counted) / of.appearances;
53
77
  //# sourceMappingURL=door.js.map
@@ -0,0 +1,192 @@
1
+ import { z } from "zod";
2
+ import { type Clock } from "../runtime/events.js";
3
+ import type { ReaderSignalJournal, ReaderSignalStoreError, ReceivedBatch } from "./journal.js";
4
+ /**
5
+ * The one operation that deletes a delivery.
6
+ *
7
+ * `collect.ts` used to be this as well: counting a ripe prefix and deleting it
8
+ * were one call, because a delivery existed for as long as it took rollup to
9
+ * read it and no longer (0146). On 5 November the maintainer settled that
10
+ * individual reader events are **kept for thirty days by default**, so that an
11
+ * operator can look at the deliveries behind a counter rather than only at the
12
+ * counter ([0349](../../decisions/0349-a-projects-reader-events-are-kept-thirty-days-by-default-and-the-tallies-stay-the-durable-record.md)),
13
+ * and the two halves of that one call became two operations with two windows
14
+ * ([0351](../../decisions/0351-a-counted-delivery-is-kept-for-a-stated-window-rather-than-deleted-by-the-fold.md)).
15
+ *
16
+ * This is the second half. It deletes and counts nothing, exactly as
17
+ * `collect.ts` counts and deletes nothing.
18
+ *
19
+ * ## The one rule, and it is not negotiable
20
+ *
21
+ * **Nothing is deleted that no fold has counted.** A delivery deleted before it
22
+ * was counted is gone from the counters too, and the counters are the durable
23
+ * record (0349) — a day of readers that nothing can reconstruct, because the
24
+ * rows that would say what they did are the rows that were deleted. So the cut
25
+ * is the lesser of two positions: the age the deployment keeps events for, and
26
+ * the oldest delivery the fold has not stamped.
27
+ *
28
+ * That means a deployment whose collection cron has stopped **stops expiring**
29
+ * rather than deleting uncounted deliveries, and says so
30
+ * ({@link ExpiryStop}). It is the same sentence the fix-list makes one level
31
+ * up — *while nothing is arriving, no reading is evidence* (0347) — about this
32
+ * table: while nothing is counting, nothing may be deleted.
33
+ *
34
+ * ## What it is not
35
+ *
36
+ * Not a scheduler, for the reason `collect.ts` is not one: when a deployment
37
+ * deletes is an operational choice, and a framework that quietly swept a host's
38
+ * data on a timer it chose would be making it. A host calls this beside
39
+ * {@link collectReaderSignals} from a cron route, a deploy hook or by hand —
40
+ * **counting first**, so that one run's fold makes its own window expirable
41
+ * rather than waiting for the next.
42
+ *
43
+ * Not idempotence-sensitive, which is the one way it is easier than collection.
44
+ * Deleting a prefix twice removes it once; there is no additive counter behind
45
+ * it and no `redelivered` to report. A run that deletes nothing is the ordinary
46
+ * answer on a deployment inside its window.
47
+ */
48
+ /**
49
+ * Thirty days, the maintainer's number, and the default of a setting rather
50
+ * than a constant (0349). Rule 5 of `docs/signals.md` is what makes it one.
51
+ *
52
+ * **It is longer than anything in this subsystem has been, and the cost is
53
+ * stated rather than buried.** A delivery carries an opaque `view` key, which
54
+ * is what correlates one page view's signals with each other and with nothing
55
+ * else (0146). While a counted delivery was deleted within the hour, the
56
+ * argument for that key rested partly on how briefly it lived; it now lives for
57
+ * as long as this window. What has not changed is what the key *is* — random
58
+ * per page view, derived from nothing about the reader, never sent back to a
59
+ * browser, and correlating nothing across two page views — so a row thirty days
60
+ * old identifies exactly nobody, which is the property the rule actually
61
+ * depends on. What has changed is that the window in which one page view's
62
+ * signals can be read together is thirty days rather than an hour, and 0349
63
+ * decided it knowing that.
64
+ *
65
+ * Shorter is cheaper and keeps less: a deployment with heavy traffic states a
66
+ * week and loses only the ability to inspect deliveries older than a week,
67
+ * because the counters keep answering over all time. Longer is what rule 5 made
68
+ * configurable in the first place.
69
+ */
70
+ export declare const DEFAULT_READER_EVENT_RETENTION_MS: number;
71
+ /**
72
+ * A minute, which is the collection window's floor and is the same mistake.
73
+ *
74
+ * It is not that a shorter window is unsafe — the rule above makes any window
75
+ * safe, because an uncounted delivery is never deleted whatever this says. It
76
+ * is that the ordinary way a window is written wrongly is a units mistake:
77
+ * `keptMs: 30` reads as thirty days and means thirty milliseconds, and a
78
+ * deployment that typed it would publish *a delivery is gone within a second*
79
+ * to every reader of its privacy page.
80
+ */
81
+ export declare const MIN_READER_EVENT_RETENTION_MS: number;
82
+ export declare const readerEventRetentionSchema: z.ZodObject<{
83
+ keptMs: z.ZodNumber;
84
+ }, "strip", z.ZodTypeAny, {
85
+ keptMs: number;
86
+ }, {
87
+ keptMs: number;
88
+ }>;
89
+ export type ReaderEventRetention = z.infer<typeof readerEventRetentionSchema>;
90
+ /** How much of the oldest end one run will look at, as collection bounds its own scan. */
91
+ export declare const DEFAULT_EXPIRY_SCAN = 5000;
92
+ export declare const MAX_EXPIRY_SCAN = 50000;
93
+ /**
94
+ * Why the cut stopped where it did, which is the one fact an operator cannot
95
+ * infer from a count of deleted rows.
96
+ *
97
+ * `uncounted` is the state worth a line in a log: nothing is wrong with this
98
+ * table, the deployment's collection has stopped, and the reason deliveries are
99
+ * piling up past the window its readers are told is that deleting them would
100
+ * lose them from the counters. The remedy is the fold's, not retention's.
101
+ */
102
+ export type ExpiryStop =
103
+ /** The oldest delivery left is inside the kept window, which is the ordinary answer. */
104
+ "young"
105
+ /** The oldest delivery left is past the window and no fold has counted it. */
106
+ | "uncounted"
107
+ /** The scan reached the end of what it read with everything expirable. */
108
+ | "end";
109
+ /**
110
+ * What one run may delete, as a pure function of rows and an instant.
111
+ *
112
+ * The cut is the **first** row that may not go, not every row that may: the
113
+ * table forgets a prefix or nothing, exactly as the journals do, because a hole
114
+ * would make `seq` — an opaque increasing position — start meaning something a
115
+ * reader could misread.
116
+ *
117
+ * **Stopping at the first is also what makes an out-of-order arrival safe.**
118
+ * `received_at` is a transaction's instant and `seq` is its position, so two
119
+ * overlapping inserts can land with the pair inverted by milliseconds. A rule
120
+ * that deleted every old row below the newest old row could then take a
121
+ * delivery younger than the window; a rule that stops at the first row it may
122
+ * not delete leaves that one and the rest of the prefix for the next run, which
123
+ * costs one interval and cannot be wrong.
124
+ */
125
+ export type ExpiryPlan = {
126
+ /** The position to delete below. `null` where nothing may go. */
127
+ readonly before: number | null;
128
+ /** Rows the scan read and left. A floor rather than a total — the scan stops at the first. */
129
+ readonly waiting: number;
130
+ readonly stopped: ExpiryStop;
131
+ };
132
+ export declare const expiryPlanOf: (scanned: readonly ReceivedBatch[], horizon: string) => ExpiryPlan;
133
+ /** The instant a delivery is old enough to go. `null` where the clock could not be read. */
134
+ export declare const keptHorizonOf: (configured: ReaderEventRetention, now: string) => string | null;
135
+ export type ExpiryOutcome = {
136
+ readonly outcome: "expired";
137
+ readonly removed: number;
138
+ /**
139
+ * How old the oldest delivery the scan read was, before anything was
140
+ * deleted, in milliseconds at this run's instant.
141
+ *
142
+ * The evidence the published retention ceiling is judged against
143
+ * ({@link retentionPromiseOf}) and the reason this figure is on the run
144
+ * rather than left to a caller's clock: a surface that read the age
145
+ * against its own `now` would publish a number nothing had measured.
146
+ *
147
+ * It is the oldest delivery **this run found**, including the ones it then
148
+ * deleted, which is what the comparison wants. A healthy run finds a row
149
+ * just past the kept window and the ceiling is that window plus one sweep,
150
+ * so it reads as kept; a run on a deployment that has not swept for a week
151
+ * finds a week.
152
+ */
153
+ readonly oldestMs: number;
154
+ readonly stopped: ExpiryStop;
155
+ /** The scan filled its limit with expirable rows, so another run has work now. */
156
+ readonly more: boolean;
157
+ }
158
+ /** Nothing in the table may go yet, which is the ordinary answer inside the window. */
159
+ | {
160
+ readonly outcome: "nothing-expired";
161
+ readonly waiting: number;
162
+ /** `null` where the scan read no row at all — a table with nothing in it. */
163
+ readonly oldestMs: number | null;
164
+ readonly stopped: ExpiryStop;
165
+ }
166
+ /** The window was not usable. Nothing was read or deleted. */
167
+ | {
168
+ readonly outcome: "refused";
169
+ readonly reason: string;
170
+ }
171
+ /** Read or delete failed. Where it was the delete, the prefix is still there. */
172
+ | {
173
+ readonly outcome: "unavailable";
174
+ readonly error: ReaderSignalStoreError;
175
+ };
176
+ export type ExpiryRequest = {
177
+ readonly keptMs?: number;
178
+ readonly clock?: Clock;
179
+ readonly scanLimit?: number;
180
+ };
181
+ /**
182
+ * Delete the deliveries this deployment no longer keeps.
183
+ *
184
+ * Called beside {@link collectReaderSignals} and after it, so that a run's own
185
+ * fold makes its own window expirable. Nothing here counts, writes a counter or
186
+ * reads a tally: the counters already hold everything these rows said, which is
187
+ * what makes deleting them safe and is the whole of 0349's second clause.
188
+ */
189
+ export declare const expireReaderEvents: (journal: ReaderSignalJournal, request?: ExpiryRequest) => Promise<ExpiryOutcome>;
190
+ /** One line for an operator, because an outcome nobody can read is one nobody acts on. */
191
+ export declare const describeExpiry: (outcome: ExpiryOutcome) => string;
192
+ //# sourceMappingURL=expire.d.ts.map
@@ -0,0 +1,213 @@
1
+ import { z } from "zod";
2
+ import { clampLimit } from "../paging.js";
3
+ import { systemClock } from "../runtime/events.js";
4
+ /**
5
+ * The one operation that deletes a delivery.
6
+ *
7
+ * `collect.ts` used to be this as well: counting a ripe prefix and deleting it
8
+ * were one call, because a delivery existed for as long as it took rollup to
9
+ * read it and no longer (0146). On 5 November the maintainer settled that
10
+ * individual reader events are **kept for thirty days by default**, so that an
11
+ * operator can look at the deliveries behind a counter rather than only at the
12
+ * counter ([0349](../../decisions/0349-a-projects-reader-events-are-kept-thirty-days-by-default-and-the-tallies-stay-the-durable-record.md)),
13
+ * and the two halves of that one call became two operations with two windows
14
+ * ([0351](../../decisions/0351-a-counted-delivery-is-kept-for-a-stated-window-rather-than-deleted-by-the-fold.md)).
15
+ *
16
+ * This is the second half. It deletes and counts nothing, exactly as
17
+ * `collect.ts` counts and deletes nothing.
18
+ *
19
+ * ## The one rule, and it is not negotiable
20
+ *
21
+ * **Nothing is deleted that no fold has counted.** A delivery deleted before it
22
+ * was counted is gone from the counters too, and the counters are the durable
23
+ * record (0349) — a day of readers that nothing can reconstruct, because the
24
+ * rows that would say what they did are the rows that were deleted. So the cut
25
+ * is the lesser of two positions: the age the deployment keeps events for, and
26
+ * the oldest delivery the fold has not stamped.
27
+ *
28
+ * That means a deployment whose collection cron has stopped **stops expiring**
29
+ * rather than deleting uncounted deliveries, and says so
30
+ * ({@link ExpiryStop}). It is the same sentence the fix-list makes one level
31
+ * up — *while nothing is arriving, no reading is evidence* (0347) — about this
32
+ * table: while nothing is counting, nothing may be deleted.
33
+ *
34
+ * ## What it is not
35
+ *
36
+ * Not a scheduler, for the reason `collect.ts` is not one: when a deployment
37
+ * deletes is an operational choice, and a framework that quietly swept a host's
38
+ * data on a timer it chose would be making it. A host calls this beside
39
+ * {@link collectReaderSignals} from a cron route, a deploy hook or by hand —
40
+ * **counting first**, so that one run's fold makes its own window expirable
41
+ * rather than waiting for the next.
42
+ *
43
+ * Not idempotence-sensitive, which is the one way it is easier than collection.
44
+ * Deleting a prefix twice removes it once; there is no additive counter behind
45
+ * it and no `redelivered` to report. A run that deletes nothing is the ordinary
46
+ * answer on a deployment inside its window.
47
+ */
48
+ /**
49
+ * Thirty days, the maintainer's number, and the default of a setting rather
50
+ * than a constant (0349). Rule 5 of `docs/signals.md` is what makes it one.
51
+ *
52
+ * **It is longer than anything in this subsystem has been, and the cost is
53
+ * stated rather than buried.** A delivery carries an opaque `view` key, which
54
+ * is what correlates one page view's signals with each other and with nothing
55
+ * else (0146). While a counted delivery was deleted within the hour, the
56
+ * argument for that key rested partly on how briefly it lived; it now lives for
57
+ * as long as this window. What has not changed is what the key *is* — random
58
+ * per page view, derived from nothing about the reader, never sent back to a
59
+ * browser, and correlating nothing across two page views — so a row thirty days
60
+ * old identifies exactly nobody, which is the property the rule actually
61
+ * depends on. What has changed is that the window in which one page view's
62
+ * signals can be read together is thirty days rather than an hour, and 0349
63
+ * decided it knowing that.
64
+ *
65
+ * Shorter is cheaper and keeps less: a deployment with heavy traffic states a
66
+ * week and loses only the ability to inspect deliveries older than a week,
67
+ * because the counters keep answering over all time. Longer is what rule 5 made
68
+ * configurable in the first place.
69
+ */
70
+ export const DEFAULT_READER_EVENT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
71
+ /**
72
+ * A minute, which is the collection window's floor and is the same mistake.
73
+ *
74
+ * It is not that a shorter window is unsafe — the rule above makes any window
75
+ * safe, because an uncounted delivery is never deleted whatever this says. It
76
+ * is that the ordinary way a window is written wrongly is a units mistake:
77
+ * `keptMs: 30` reads as thirty days and means thirty milliseconds, and a
78
+ * deployment that typed it would publish *a delivery is gone within a second*
79
+ * to every reader of its privacy page.
80
+ */
81
+ export const MIN_READER_EVENT_RETENTION_MS = 60 * 1000;
82
+ export const readerEventRetentionSchema = z.object({
83
+ keptMs: z.number().int().min(MIN_READER_EVENT_RETENTION_MS),
84
+ });
85
+ /** How much of the oldest end one run will look at, as collection bounds its own scan. */
86
+ export const DEFAULT_EXPIRY_SCAN = 5_000;
87
+ export const MAX_EXPIRY_SCAN = 50_000;
88
+ /** Read in pages like every other log walk (0026), so memory is bounded by the page. */
89
+ const SCAN_PAGE = 500;
90
+ /** Past the window **and** counted. Both, which is the rule at the top of this file. */
91
+ const expirable = (batch, horizon) => batch.receivedAt < horizon && batch.foldedAt !== undefined;
92
+ export const expiryPlanOf = (scanned, horizon) => {
93
+ const ceiling = scanned.findIndex((batch) => !expirable(batch, horizon));
94
+ const going = ceiling === -1 ? scanned : scanned.slice(0, ceiling);
95
+ const held = ceiling === -1 ? undefined : scanned[ceiling];
96
+ const last = going.at(-1);
97
+ return {
98
+ before: last === undefined ? null : last.seq + 1,
99
+ waiting: scanned.length - going.length,
100
+ stopped: held === undefined ? "end" : held.receivedAt < horizon ? "uncounted" : "young",
101
+ };
102
+ };
103
+ /** The instant a delivery is old enough to go. `null` where the clock could not be read. */
104
+ export const keptHorizonOf = (configured, now) => {
105
+ const instant = Date.parse(now);
106
+ return Number.isFinite(instant) ? new Date(instant - configured.keptMs).toISOString() : null;
107
+ };
108
+ /**
109
+ * The oldest end of the table, forward, stopping at the first row that may not
110
+ * go.
111
+ *
112
+ * Every row from there on is kept by this run, and `expiryPlanOf` needs only
113
+ * the first of them to know where the prefix ends — so reading further would be
114
+ * reading the kept window to throw it away.
115
+ *
116
+ * **Counted and uncounted together**, unlike collection's scan, because the
117
+ * uncounted row is half of what this is looking for: a scan that filtered it
118
+ * out would delete straight through the gap it exists to stop at.
119
+ */
120
+ const scanFrom = async (journal, horizon, scanLimit) => {
121
+ const collected = [];
122
+ let cursor;
123
+ while (collected.length < scanLimit) {
124
+ const page = await journal.read({
125
+ direction: "newer",
126
+ limit: Math.min(SCAN_PAGE, scanLimit - collected.length),
127
+ ...(cursor ? { cursor } : {}),
128
+ });
129
+ if (!page.ok)
130
+ return { ok: false, error: page.error };
131
+ collected.push(...page.value.batches);
132
+ if (page.value.batches.some((batch) => !expirable(batch, horizon))) {
133
+ return { ok: true, batches: collected, full: false };
134
+ }
135
+ if (page.value.newer === null)
136
+ return { ok: true, batches: collected, full: false };
137
+ cursor = page.value.newer;
138
+ }
139
+ return { ok: true, batches: collected, full: true };
140
+ };
141
+ /**
142
+ * Delete the deliveries this deployment no longer keeps.
143
+ *
144
+ * Called beside {@link collectReaderSignals} and after it, so that a run's own
145
+ * fold makes its own window expirable. Nothing here counts, writes a counter or
146
+ * reads a tally: the counters already hold everything these rows said, which is
147
+ * what makes deleting them safe and is the whole of 0349's second clause.
148
+ */
149
+ export const expireReaderEvents = async (journal, request = {}) => {
150
+ const configured = readerEventRetentionSchema.safeParse({
151
+ keptMs: request.keptMs ?? DEFAULT_READER_EVENT_RETENTION_MS,
152
+ });
153
+ if (!configured.success) {
154
+ return { outcome: "refused", reason: configured.error.issues[0]?.message ?? "invalid window" };
155
+ }
156
+ const now = (request.clock ?? systemClock).now();
157
+ const horizon = keptHorizonOf(configured.data, now);
158
+ if (horizon === null)
159
+ return { outcome: "refused", reason: `the clock read "${now}"` };
160
+ const scanned = await scanFrom(journal, horizon, clampLimit(request.scanLimit, { fallback: DEFAULT_EXPIRY_SCAN, max: MAX_EXPIRY_SCAN }));
161
+ if (!scanned.ok)
162
+ return { outcome: "unavailable", error: scanned.error };
163
+ const plan = expiryPlanOf(scanned.batches, horizon);
164
+ const oldest = scanned.batches[0];
165
+ /**
166
+ * The age of the oldest row the scan read, which is the oldest row there is:
167
+ * the scan runs from the oldest end. Absent only where it read nothing.
168
+ */
169
+ const oldestMs = oldest === undefined ? null : Date.parse(now) - Date.parse(oldest.receivedAt);
170
+ if (plan.before === null) {
171
+ return {
172
+ outcome: "nothing-expired",
173
+ waiting: plan.waiting,
174
+ oldestMs,
175
+ stopped: plan.stopped,
176
+ };
177
+ }
178
+ const forgotten = await journal.forget({ before: plan.before });
179
+ if (!forgotten.ok)
180
+ return { outcome: "unavailable", error: forgotten.error };
181
+ return {
182
+ outcome: "expired",
183
+ removed: forgotten.value.removed,
184
+ /** A plan with a position has a first row, so the age is a number here. */
185
+ oldestMs: oldestMs ?? Number.NaN,
186
+ stopped: plan.stopped,
187
+ more: scanned.full,
188
+ };
189
+ };
190
+ const deliveries = (count) => `${count} ${count === 1 ? "delivery" : "deliveries"}`;
191
+ /**
192
+ * Said only where it changes what an operator should do, which is the one
193
+ * state where the remedy is somebody else's: the fold's.
194
+ */
195
+ const held = (stopped) => stopped === "uncounted"
196
+ ? " — the next one is past the window and uncounted, so collection has stopped and nothing further may go"
197
+ : "";
198
+ /** One line for an operator, because an outcome nobody can read is one nobody acts on. */
199
+ export const describeExpiry = (outcome) => {
200
+ switch (outcome.outcome) {
201
+ case "expired":
202
+ return `deleted ${deliveries(outcome.removed)}${held(outcome.stopped)}${outcome.more ? " — more is waiting" : ""}`;
203
+ case "nothing-expired":
204
+ return outcome.oldestMs === null
205
+ ? "nothing is kept, so nothing is old enough to delete"
206
+ : `nothing is old enough to delete, ${deliveries(outcome.waiting)} kept and the oldest ${outcome.oldestMs}ms old${held(outcome.stopped)}`;
207
+ case "refused":
208
+ return `expiry refused: ${outcome.reason}`;
209
+ case "unavailable":
210
+ return `expiry could not run: ${outcome.error.detail}`;
211
+ }
212
+ };
213
+ //# sourceMappingURL=expire.js.map