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