@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.
- package/dist/audience/compose.d.ts +112 -0
- package/dist/audience/compose.js +134 -0
- package/dist/audience/memory.d.ts +14 -0
- package/dist/audience/memory.js +71 -0
- package/dist/audience/overlay-store.d.ts +343 -0
- package/dist/audience/overlay-store.js +217 -0
- package/dist/audience/rule.d.ts +121 -0
- package/dist/audience/rule.js +78 -0
- package/dist/cli/index.d.ts +3 -4
- package/dist/cli/index.js +3 -4
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/resolve.d.ts +1 -1
- package/dist/interpretation/anthropic.d.ts +1 -1
- package/dist/interpretation/anthropic.js +2 -22
- package/dist/interpretation/client.d.ts +1 -1
- package/dist/interpretation/materialize.js +67 -22
- package/dist/interpretation/openai-compatible.d.ts +36 -0
- package/dist/interpretation/openai-compatible.js +79 -0
- package/dist/interpretation/status.d.ts +19 -0
- package/dist/interpretation/status.js +26 -0
- package/dist/live/index.d.ts +73 -0
- package/dist/live/index.js +73 -0
- package/dist/live/pages.d.ts +187 -0
- package/dist/live/pages.js +161 -0
- package/dist/live/pull.d.ts +147 -0
- package/dist/live/pull.js +398 -0
- package/dist/live/pulling.d.ts +79 -0
- package/dist/live/pulling.js +117 -0
- package/dist/live/window.d.ts +129 -0
- package/dist/live/window.js +132 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/document-theme.d.ts +70 -0
- package/dist/render/document-theme.js +139 -0
- package/dist/render/editable.d.ts +15 -1
- package/dist/render/editable.js +13 -1
- package/dist/render/expected.d.ts +98 -0
- package/dist/render/expected.js +88 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +192 -46
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/gate.js +69 -10
- package/dist/runtime/index.d.ts +1 -0
- package/dist/runtime/index.js +1 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/policy-change.js +8 -2
- package/dist/runtime/policy-log.d.ts +5 -5
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/sdk/definition.d.ts +65 -6
- package/dist/sdk/definition.js +44 -0
- package/dist/sdk/registry.d.ts +17 -1
- package/dist/sdk/registry.js +39 -0
- package/dist/signals/acted.contract.d.ts +21 -0
- package/dist/signals/acted.contract.js +236 -0
- package/dist/signals/acted.d.ts +359 -0
- package/dist/signals/acted.js +135 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/arrivals.contract.d.ts +21 -0
- package/dist/signals/arrivals.contract.js +180 -0
- package/dist/signals/arrivals.d.ts +375 -0
- package/dist/signals/arrivals.js +254 -0
- package/dist/signals/broadcast.d.ts +25 -15
- package/dist/signals/broadcast.js +209 -36
- package/dist/signals/collect.d.ts +137 -43
- package/dist/signals/collect.js +103 -36
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +51 -0
- package/dist/signals/counters.js +58 -0
- package/dist/signals/deployment-change.d.ts +28 -4
- package/dist/signals/deployment-change.js +57 -16
- package/dist/signals/deployment.d.ts +18 -5
- package/dist/signals/deployment.js +37 -11
- package/dist/signals/door.d.ts +34 -12
- package/dist/signals/door.js +37 -13
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-hours.contract.d.ts +21 -0
- package/dist/signals/funnel-hours.contract.js +221 -0
- package/dist/signals/funnel-hours.d.ts +293 -0
- package/dist/signals/funnel-hours.js +99 -0
- package/dist/signals/funnel.d.ts +60 -0
- package/dist/signals/funnel.js +35 -20
- package/dist/signals/health.d.ts +201 -4
- package/dist/signals/health.js +214 -2
- package/dist/signals/index.d.ts +19 -0
- package/dist/signals/index.js +19 -0
- package/dist/signals/inside.d.ts +190 -0
- package/dist/signals/inside.js +263 -0
- package/dist/signals/join.d.ts +56 -0
- package/dist/signals/join.js +60 -0
- package/dist/signals/journal.d.ts +112 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/library-agenda-change.d.ts +324 -0
- package/dist/signals/library-agenda-change.js +199 -0
- package/dist/signals/library-agenda.d.ts +258 -0
- package/dist/signals/library-agenda.js +167 -0
- package/dist/signals/library-reach-change.d.ts +10 -0
- package/dist/signals/library-reach-change.js +11 -3
- package/dist/signals/library-senders-change.d.ts +457 -0
- package/dist/signals/library-senders-change.js +367 -0
- package/dist/signals/library-senders-reach-change.d.ts +486 -0
- package/dist/signals/library-senders-reach-change.js +538 -0
- package/dist/signals/library-senders-reach.d.ts +340 -0
- package/dist/signals/library-senders-reach.js +252 -0
- package/dist/signals/library-senders.d.ts +271 -0
- package/dist/signals/library-senders.js +180 -0
- package/dist/signals/library-word-reach-change.js +2 -6
- package/dist/signals/memory.js +142 -1
- package/dist/signals/migrate.d.ts +6 -5
- package/dist/signals/migrate.js +150 -6
- package/dist/signals/notice.d.ts +88 -33
- package/dist/signals/notice.js +38 -16
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +25 -15
- package/dist/signals/parts.js +32 -73
- package/dist/signals/postgres.js +400 -26
- package/dist/signals/region.d.ts +1 -1
- package/dist/signals/retention.d.ts +43 -21
- package/dist/signals/retention.js +25 -8
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +127 -1
- package/dist/signals/rollup.js +211 -24
- package/dist/signals/schema.d.ts +640 -3
- package/dist/signals/schema.js +239 -3
- package/dist/signals/silences.d.ts +310 -11
- package/dist/signals/silences.js +243 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +125 -4
- package/dist/signals/unread.d.ts +292 -0
- package/dist/signals/unread.js +137 -0
- package/dist/signals/window-agenda.d.ts +276 -0
- package/dist/signals/window-agenda.js +83 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/store/cache.d.ts +101 -0
- package/dist/store/cache.js +149 -0
- package/dist/store/history.d.ts +82 -0
- package/dist/store/history.js +36 -0
- package/dist/store/index.d.ts +11 -0
- package/dist/store/index.js +11 -0
- package/dist/store/migrate.d.ts +26 -0
- package/dist/store/migrate.js +64 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres.d.ts +1 -0
- package/dist/store/postgres.js +1 -0
- package/dist/store/schema.d.ts +312 -0
- package/dist/store/schema.js +77 -0
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +32 -0
- package/dist/telemetry/memory.js +10 -1
- package/dist/telemetry/postgres.js +18 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/audience-overlay-contract.d.ts +31 -0
- package/dist/testing/audience-overlay-contract.js +354 -0
- package/dist/testing/contracts.d.ts +1 -0
- package/dist/testing/contracts.js +1 -0
- package/dist/testing/journal-contract.js +158 -5
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/tree/apply.js +13 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +24 -12
- package/dist/tree/navigation.d.ts +5 -0
- package/dist/tree/navigation.js +32 -10
- package/dist/tree/outline.d.ts +7 -0
- package/dist/tree/outline.js +9 -5
- package/package.json +39 -96
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- 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
|
-
* `
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
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
|
-
|
|
28
|
-
return
|
|
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
|
|
116
|
+
readers: atDoorScale(at.lost, doorOf(door)),
|
|
91
117
|
share: at.share,
|
|
92
118
|
};
|
|
93
119
|
};
|
package/dist/signals/door.d.ts
CHANGED
|
@@ -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
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
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
|
-
* **
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
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
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
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
|
package/dist/signals/door.js
CHANGED
|
@@ -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
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
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
|
-
* **
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
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
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
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) =>
|
|
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
|