@jam-overture/loom 0.1.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/README.md +3 -1
- package/dist/application/application.d.ts +109 -0
- package/dist/application/application.js +97 -0
- package/dist/application/memory.d.ts +20 -0
- package/dist/application/memory.js +79 -0
- package/dist/application/store.d.ts +101 -0
- package/dist/application/store.js +25 -0
- package/dist/audience/audience.d.ts +36 -0
- package/dist/audience/audience.js +41 -0
- 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/cli/templates.js +19 -0
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +23 -1
- package/dist/data/resolve.d.ts +31 -4
- package/dist/data/resolve.js +11 -3
- package/dist/ids.d.ts +10 -0
- package/dist/ids.js +11 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- 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/patch.d.ts +54 -0
- package/dist/patch.js +44 -0
- package/dist/project/closing.d.ts +51 -0
- package/dist/project/closing.js +53 -0
- package/dist/project/memory.d.ts +20 -0
- package/dist/project/memory.js +97 -0
- package/dist/project/project.d.ts +90 -0
- package/dist/project/project.js +91 -0
- package/dist/project/store.d.ts +135 -0
- package/dist/project/store.js +41 -0
- package/dist/registered.d.ts +64 -0
- package/dist/registered.js +118 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/behaviour-adjust.d.ts +11 -19
- package/dist/render/behaviour-adjust.js +75 -21
- package/dist/render/behaviour-present.d.ts +8 -0
- package/dist/render/behaviour-present.js +57 -6
- package/dist/render/behaviour.d.ts +98 -17
- package/dist/render/behaviour.js +91 -26
- package/dist/render/control-name.d.ts +68 -0
- package/dist/render/control-name.js +37 -0
- package/dist/render/diagnostics.d.ts +72 -0
- package/dist/render/diagnostics.js +7 -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 +4 -0
- package/dist/render/index.js +4 -0
- package/dist/render/reads.d.ts +11 -0
- package/dist/render/reads.js +12 -1
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +294 -53
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/render/slots.d.ts +52 -0
- package/dist/render/slots.js +24 -0
- package/dist/render/theme.d.ts +54 -1
- package/dist/render/theme.js +23 -1
- package/dist/render/unshown.d.ts +152 -0
- package/dist/render/unshown.js +80 -0
- package/dist/runtime/analysis.d.ts +94 -9
- package/dist/runtime/analysis.js +54 -9
- package/dist/runtime/assessment.d.ts +36 -2
- package/dist/runtime/assessment.js +27 -2
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/checks.d.ts +148 -0
- package/dist/runtime/checks.js +112 -0
- package/dist/runtime/disposition.d.ts +96 -0
- package/dist/runtime/disposition.js +46 -0
- package/dist/runtime/gate.js +91 -10
- package/dist/runtime/index.d.ts +4 -0
- package/dist/runtime/index.js +4 -0
- package/dist/runtime/irreversibility.d.ts +64 -0
- package/dist/runtime/irreversibility.js +45 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/pipeline.d.ts +43 -0
- package/dist/runtime/pipeline.js +10 -2
- package/dist/runtime/policy-change.d.ts +93 -0
- package/dist/runtime/policy-change.js +305 -0
- package/dist/runtime/policy-log.d.ts +406 -0
- package/dist/runtime/policy-log.js +285 -0
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +11 -9
- package/dist/runtime/stakes.d.ts +129 -1
- package/dist/runtime/stakes.js +240 -26
- package/dist/runtime/vocabulary.d.ts +164 -7
- package/dist/runtime/vocabulary.js +181 -8
- package/dist/sdk/audit.d.ts +174 -3
- package/dist/sdk/audit.js +176 -17
- package/dist/sdk/catalogue.d.ts +9 -1
- package/dist/sdk/conformance.d.ts +37 -3
- package/dist/sdk/conformance.js +25 -4
- package/dist/sdk/definition.d.ts +129 -5
- package/dist/sdk/definition.js +66 -0
- package/dist/sdk/registry.d.ts +45 -2
- package/dist/sdk/registry.js +102 -1
- 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/action-change.d.ts +507 -0
- package/dist/signals/action-change.js +265 -0
- package/dist/signals/action.d.ts +331 -0
- package/dist/signals/action.js +182 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/applied-window.contract.d.ts +23 -0
- package/dist/signals/applied-window.contract.js +160 -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/arriving.d.ts +210 -0
- package/dist/signals/arriving.js +133 -0
- package/dist/signals/audiences.d.ts +528 -0
- package/dist/signals/audiences.js +255 -0
- package/dist/signals/broadcast.d.ts +33 -17
- package/dist/signals/broadcast.js +255 -32
- package/dist/signals/change.d.ts +378 -0
- package/dist/signals/change.js +327 -0
- package/dist/signals/collect.d.ts +169 -34
- package/dist/signals/collect.js +186 -38
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/copy-change.d.ts +553 -0
- package/dist/signals/copy-change.js +377 -0
- package/dist/signals/copy.d.ts +337 -0
- package/dist/signals/copy.js +211 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +97 -0
- package/dist/signals/counters.js +160 -0
- package/dist/signals/deliver.d.ts +23 -4
- package/dist/signals/deliver.js +34 -6
- package/dist/signals/deployment-change.d.ts +395 -0
- package/dist/signals/deployment-change.js +309 -0
- package/dist/signals/deployment.d.ts +278 -0
- package/dist/signals/deployment.js +178 -0
- package/dist/signals/door.d.ts +114 -0
- package/dist/signals/door.js +77 -0
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/fold.d.ts +10 -0
- package/dist/signals/fold.js +5 -1
- package/dist/signals/form-action.d.ts +302 -0
- package/dist/signals/form-action.js +169 -0
- package/dist/signals/form-copy.d.ts +523 -0
- package/dist/signals/form-copy.js +346 -0
- package/dist/signals/forms.d.ts +247 -0
- package/dist/signals/forms.js +147 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-change.d.ts +548 -0
- package/dist/signals/funnel-change.js +361 -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 +592 -0
- package/dist/signals/funnel.js +231 -0
- package/dist/signals/health.d.ts +694 -0
- package/dist/signals/health.js +573 -0
- package/dist/signals/index.d.ts +60 -0
- package/dist/signals/index.js +60 -0
- package/dist/signals/ingest.d.ts +56 -1
- package/dist/signals/ingest.js +91 -1
- 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 +123 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/kinds.d.ts +8 -6
- package/dist/signals/kinds.js +14 -6
- package/dist/signals/library-action.d.ts +430 -0
- package/dist/signals/library-action.js +336 -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-change.d.ts +477 -0
- package/dist/signals/library-change.js +335 -0
- package/dist/signals/library-copy-change.d.ts +498 -0
- package/dist/signals/library-copy-change.js +476 -0
- package/dist/signals/library-pace.d.ts +319 -0
- package/dist/signals/library-pace.js +305 -0
- package/dist/signals/library-reach-change.d.ts +646 -0
- package/dist/signals/library-reach-change.js +542 -0
- package/dist/signals/library-reach.d.ts +377 -0
- package/dist/signals/library-reach.js +227 -0
- 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.d.ts +567 -0
- package/dist/signals/library-word-reach-change.js +564 -0
- package/dist/signals/library.d.ts +306 -0
- package/dist/signals/library.js +178 -0
- package/dist/signals/memory.d.ts +9 -0
- package/dist/signals/memory.js +246 -14
- package/dist/signals/migrate.d.ts +20 -4
- package/dist/signals/migrate.js +269 -8
- package/dist/signals/notice.d.ts +389 -0
- package/dist/signals/notice.js +250 -0
- package/dist/signals/pace-change.d.ts +501 -0
- package/dist/signals/pace-change.js +310 -0
- package/dist/signals/pace.d.ts +296 -0
- package/dist/signals/pace.js +291 -0
- package/dist/signals/page-views.d.ts +365 -0
- package/dist/signals/page-views.js +218 -0
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +354 -0
- package/dist/signals/parts.js +232 -0
- package/dist/signals/postgres.d.ts +16 -2
- package/dist/signals/postgres.js +753 -76
- package/dist/signals/progress.d.ts +212 -0
- package/dist/signals/progress.js +150 -0
- package/dist/signals/ratios.d.ts +108 -0
- package/dist/signals/ratios.js +40 -0
- package/dist/signals/reach.d.ts +309 -0
- package/dist/signals/reach.js +93 -0
- package/dist/signals/readable.d.ts +34 -0
- package/dist/signals/readable.js +34 -0
- package/dist/signals/readership.d.ts +381 -0
- package/dist/signals/readership.js +308 -0
- package/dist/signals/region-pages.d.ts +173 -0
- package/dist/signals/region-pages.js +62 -0
- package/dist/signals/region.d.ts +287 -0
- package/dist/signals/region.js +198 -0
- package/dist/signals/retention.d.ts +163 -0
- package/dist/signals/retention.js +75 -0
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +194 -4
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +1069 -1
- package/dist/signals/schema.js +393 -3
- package/dist/signals/signal.d.ts +237 -11
- package/dist/signals/signal.js +70 -10
- package/dist/signals/silence-census.d.ts +205 -0
- package/dist/signals/silence-census.js +87 -0
- package/dist/signals/silences.d.ts +1147 -0
- package/dist/signals/silences.js +996 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +262 -12
- 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-figures.d.ts +148 -0
- package/dist/signals/window-figures.js +42 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/signals/window.d.ts +866 -0
- package/dist/signals/window.js +693 -0
- package/dist/signals/words.d.ts +24 -0
- package/dist/signals/words.js +24 -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 +30 -0
- package/dist/store/index.js +30 -0
- package/dist/store/memory.d.ts +2 -1
- package/dist/store/memory.js +48 -12
- package/dist/store/migrate.d.ts +106 -0
- package/dist/store/migrate.js +323 -7
- package/dist/store/postgres-applications.d.ts +4 -0
- package/dist/store/postgres-applications.js +197 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres-holds.d.ts +10 -1
- package/dist/store/postgres-holds.js +116 -101
- package/dist/store/postgres-policy-log.d.ts +14 -0
- package/dist/store/postgres-policy-log.js +240 -0
- package/dist/store/postgres-projects.d.ts +4 -0
- package/dist/store/postgres-projects.js +217 -0
- package/dist/store/postgres.d.ts +17 -1
- package/dist/store/postgres.js +60 -9
- package/dist/store/replay.d.ts +102 -1
- package/dist/store/replay.js +190 -19
- package/dist/store/reseed.d.ts +238 -0
- package/dist/store/reseed.js +308 -0
- package/dist/store/schema.d.ts +762 -2
- package/dist/store/schema.js +218 -5
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/store/store.d.ts +29 -6
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/submit/resolve.js +2 -1
- package/dist/telemetry/calibration.d.ts +25 -0
- package/dist/telemetry/calibration.js +27 -1
- package/dist/telemetry/event.d.ts +391 -33
- package/dist/telemetry/event.js +84 -20
- package/dist/telemetry/index.d.ts +2 -0
- package/dist/telemetry/index.js +2 -0
- package/dist/telemetry/journal.d.ts +104 -3
- package/dist/telemetry/journal.js +9 -0
- package/dist/telemetry/lookup.d.ts +27 -0
- package/dist/telemetry/lookup.js +18 -0
- package/dist/telemetry/memory.js +33 -1
- package/dist/telemetry/migrate.js +22 -1
- package/dist/telemetry/postgres.d.ts +10 -1
- package/dist/telemetry/postgres.js +188 -90
- package/dist/telemetry/remeasure.d.ts +78 -0
- package/dist/telemetry/remeasure.js +83 -0
- package/dist/telemetry/retention.d.ts +2 -2
- package/dist/telemetry/schema.d.ts +17 -0
- package/dist/telemetry/schema.js +27 -1
- package/dist/telemetry/sink.d.ts +2 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/application-contract.d.ts +14 -0
- package/dist/testing/application-contract.js +270 -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 +13 -7
- package/dist/testing/contracts.js +13 -7
- package/dist/testing/definitions.d.ts +78 -0
- package/dist/testing/definitions.js +134 -9
- package/dist/testing/doubles.d.ts +103 -0
- package/dist/testing/doubles.js +143 -0
- package/dist/testing/index.d.ts +2 -2
- package/dist/testing/index.js +2 -2
- package/dist/testing/journal-contract.js +297 -6
- package/dist/testing/model-contract.d.ts +110 -0
- package/dist/testing/model-contract.js +150 -0
- package/dist/testing/policy-log-contract.d.ts +26 -0
- package/dist/testing/policy-log-contract.js +344 -0
- package/dist/testing/project-contract.d.ts +14 -0
- package/dist/testing/project-contract.js +266 -0
- package/dist/testing/reader-signal-contract.d.ts +27 -2
- package/dist/testing/reader-signal-contract.js +475 -5
- package/dist/testing/store-contract.d.ts +7 -1
- package/dist/testing/store-contract.js +84 -3
- package/dist/theme/apply.d.ts +20 -1
- package/dist/theme/apply.js +5 -3
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/theme/derive.d.ts +22 -0
- package/dist/theme/derive.js +54 -1
- package/dist/theme/library.js +1 -1
- package/dist/theme/measure.d.ts +34 -0
- package/dist/theme/measure.js +30 -1
- package/dist/theme/palettes.js +7 -7
- package/dist/theme/ramp.d.ts +64 -0
- package/dist/theme/ramp.js +114 -0
- package/dist/theme/registry.d.ts +9 -0
- package/dist/theme/registry.js +11 -1
- package/dist/theme/separation.d.ts +97 -3
- package/dist/theme/separation.js +75 -0
- package/dist/tree/apply.js +13 -0
- package/dist/tree/compare.d.ts +9 -0
- package/dist/tree/compare.js +18 -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/dist/write/computed.d.ts +60 -0
- package/dist/write/computed.js +61 -0
- package/dist/write/held.d.ts +59 -0
- package/dist/write/index.d.ts +5 -2
- package/dist/write/index.js +5 -2
- package/dist/write/reseed.d.ts +151 -0
- package/dist/write/reseed.js +184 -0
- package/dist/write/revert.js +2 -16
- package/package.json +25 -3
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- package/dist/runtime/inverse-interpreter.js +0 -56
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { AudienceId } from "../audience/audience.js";
|
|
3
|
+
import type { TreeId } from "../ids.js";
|
|
4
|
+
import type { Result } from "../result.js";
|
|
5
|
+
import type { ReaderSignalStoreError } from "./journal.js";
|
|
6
|
+
import type { RevisionOf, RevisionViews } from "./page-views.js";
|
|
7
|
+
import type { TallyReadRequest } from "./tally.js";
|
|
8
|
+
/**
|
|
9
|
+
* A region nobody can name.
|
|
10
|
+
*
|
|
11
|
+
* A deployment behind a proxy that adds no such header, a request from a
|
|
12
|
+
* development machine, a header holding something that is not a country code —
|
|
13
|
+
* all of them are this, and it is a bucket rather than a dropped row. *We do
|
|
14
|
+
* not know where 40 of these views came from* is a fact about the measurement;
|
|
15
|
+
* silently keeping only the views that could be placed is a figure that looks
|
|
16
|
+
* complete and is not.
|
|
17
|
+
*
|
|
18
|
+
* Seven characters, so it can never collide with a two-letter code.
|
|
19
|
+
*/
|
|
20
|
+
export declare const UNKNOWN_REGION: ReaderRegion;
|
|
21
|
+
/** Two uppercase letters, which is what a country code is. */
|
|
22
|
+
export declare const regionPattern: RegExp;
|
|
23
|
+
/**
|
|
24
|
+
* A country, or the admission that there is none.
|
|
25
|
+
*
|
|
26
|
+
* Deliberately no narrower. A subdivision or a city is the step from *where our
|
|
27
|
+
* readers are* to *who that reader was* — a city plus a count of two is a
|
|
28
|
+
* person with an address — and the header carrying one is sitting beside the
|
|
29
|
+
* header this reads. It is not read.
|
|
30
|
+
*
|
|
31
|
+
* Deliberately no wider either: the value becomes a column, and a column fed
|
|
32
|
+
* from a request header is a column a caller can write to. Two letters or the
|
|
33
|
+
* one sentinel is a closed set, so the worst a poisoned header can do is add to
|
|
34
|
+
* a bucket that already exists.
|
|
35
|
+
*/
|
|
36
|
+
export declare const readerRegionSchema: z.ZodBranded<z.ZodUnion<[z.ZodLiteral<"unknown">, z.ZodString]>, "ReaderRegion">;
|
|
37
|
+
export type ReaderRegion = z.infer<typeof readerRegionSchema>;
|
|
38
|
+
/**
|
|
39
|
+
* Read a region off whatever the platform wrote, and never fail.
|
|
40
|
+
*
|
|
41
|
+
* Trimmed and upper-cased because headers are written by whoever is in front of
|
|
42
|
+
* the application and casing is not a thing to have an opinion about. Anything
|
|
43
|
+
* that is not a country code — absent, empty, a city, a word, the Tor marker
|
|
44
|
+
* some platforms send — is unplaced rather than refused: this runs on the
|
|
45
|
+
* request path of the one public write endpoint, and a region that cannot be
|
|
46
|
+
* read is a bucket, not an error.
|
|
47
|
+
*/
|
|
48
|
+
export declare const readerRegionOf: (given: string | null | undefined) => ReaderRegion;
|
|
49
|
+
/**
|
|
50
|
+
* Page views from one region, of one revision of one tree.
|
|
51
|
+
*
|
|
52
|
+
* Keyed the way every durable counter in this subsystem is keyed — a signal
|
|
53
|
+
* about the fourth section means nothing once a proposal has moved it — so a
|
|
54
|
+
* region's number is answerable before and after a change rather than smeared
|
|
55
|
+
* across both.
|
|
56
|
+
*/
|
|
57
|
+
export type ReaderRegionCount = {
|
|
58
|
+
readonly treeId: TreeId;
|
|
59
|
+
readonly revision: number;
|
|
60
|
+
readonly region: ReaderRegion;
|
|
61
|
+
/** Page views that *began* here, so a longer visit is not a bigger number. */
|
|
62
|
+
readonly views: number;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* A region count as the store keeps it: the count, the audience it was
|
|
66
|
+
* collected under, and when it last moved. See `StoredTally.audienceId` (0284).
|
|
67
|
+
*/
|
|
68
|
+
export type StoredRegionCount = ReaderRegionCount & {
|
|
69
|
+
readonly audienceId: AudienceId;
|
|
70
|
+
readonly updatedAt: string;
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* The durable half, and the only one there is — a region has no raw form to
|
|
74
|
+
* expire, because it was never written down as an observation.
|
|
75
|
+
*
|
|
76
|
+
* Written by the intake, on the request path, which is what distinguishes this
|
|
77
|
+
* from the per-node counters: those are written by a rollup over a window, and
|
|
78
|
+
* a region cannot be, because by then the request it was read from is gone.
|
|
79
|
+
*/
|
|
80
|
+
export interface ReaderRegionStore {
|
|
81
|
+
/**
|
|
82
|
+
* Add views to the buckets they belong in, creating rows that do not exist
|
|
83
|
+
* yet. Additive for the same reason applying a rollup is: every call reports
|
|
84
|
+
* what just arrived rather than what is true so far.
|
|
85
|
+
*/
|
|
86
|
+
readonly count: (counts: readonly ReaderRegionCount[], at: string,
|
|
87
|
+
/** The audience the delivery was served under (0284). Omitted is `aud_everyone`. */
|
|
88
|
+
audience?: AudienceId) => Promise<Result<void, ReaderSignalStoreError>>;
|
|
89
|
+
readonly regions: (request?: TallyReadRequest) => Promise<Result<readonly StoredRegionCount[], ReaderSignalStoreError>>;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* What one delivery adds, which is one view per page view it opened.
|
|
93
|
+
*
|
|
94
|
+
* **It is handed the openings rather than the delivery**, so that a region can
|
|
95
|
+
* only ever be a stamp on a page view somebody already counted. The walk that
|
|
96
|
+
* finds them, and the deduplication that makes a retried opening one arrival
|
|
97
|
+
* rather than two, is `openingsOf` in `page-views.ts` — shared deliberately,
|
|
98
|
+
* because two counters that each decided for themselves how many readers
|
|
99
|
+
* arrived would sooner or later disagree about it, and the disagreement would
|
|
100
|
+
* surface as a map whose numbers do not add up to the number of page views
|
|
101
|
+
* there were.
|
|
102
|
+
*
|
|
103
|
+
* A delivery that opened nothing adds nothing, and a sender that never says
|
|
104
|
+
* adds nothing at all — which is the honest answer for a batch synthesised on a
|
|
105
|
+
* server or replayed from a fixture, exactly as such a batch adds nothing to
|
|
106
|
+
* any view count.
|
|
107
|
+
*/
|
|
108
|
+
export declare const regionCountsOf: (openings: readonly RevisionViews[], region: ReaderRegion) => readonly ReaderRegionCount[];
|
|
109
|
+
/**
|
|
110
|
+
* The smallest a bucket may be before it is named.
|
|
111
|
+
*
|
|
112
|
+
* Twenty-five, and the number is a judgement rather than a derivation: it is
|
|
113
|
+
* low enough that a deployment with a few hundred readers sees its own map, and
|
|
114
|
+
* high enough that no bucket is one person, one household or one office. A
|
|
115
|
+
* deployment that wants more caution raises it.
|
|
116
|
+
*
|
|
117
|
+
* It is not lowerable, and that is the one place this subsystem overrides an
|
|
118
|
+
* operator. The floor is what makes the aggregate an aggregate; a deployment
|
|
119
|
+
* that could set it to one would be running a different product, and the
|
|
120
|
+
* difference would be invisible on the screen that showed the result.
|
|
121
|
+
*/
|
|
122
|
+
export declare const DEFAULT_REGION_FLOOR = 25;
|
|
123
|
+
/**
|
|
124
|
+
* The floor that will actually be used, given what somebody asked for.
|
|
125
|
+
*
|
|
126
|
+
* Raise-only, and anything that is not a whole number of views is the default —
|
|
127
|
+
* a floor read from configuration is read from a string somebody typed, and the
|
|
128
|
+
* direction to be wrong in is the cautious one.
|
|
129
|
+
*/
|
|
130
|
+
export declare const regionFloorOf: (asked: number | undefined) => number;
|
|
131
|
+
/** One region, as a reading reports it. */
|
|
132
|
+
export type RegionBucket = {
|
|
133
|
+
readonly region: ReaderRegion;
|
|
134
|
+
readonly views: number;
|
|
135
|
+
};
|
|
136
|
+
export type RegionReading = {
|
|
137
|
+
/** The floor the rows were read at, so a screen can say what it is withholding by. */
|
|
138
|
+
readonly floor: number;
|
|
139
|
+
/**
|
|
140
|
+
* The audience whose arrivals this map is of, or `null` where nothing said.
|
|
141
|
+
*
|
|
142
|
+
* {@link regionReadingFor} names it, because it picked the rows of one
|
|
143
|
+
* audience to build the map from. {@link regionReadingOf} leaves it `null`,
|
|
144
|
+
* because it groups whatever it is handed and a deployment's whole window is
|
|
145
|
+
* a readership rather than one form's.
|
|
146
|
+
*
|
|
147
|
+
* Carried so that a comparison of two maps can refuse a pair of two
|
|
148
|
+
* populations (0284). It is the one thing a readership comparison cannot
|
|
149
|
+
* derive and the one thing that makes it a comparison of like with like.
|
|
150
|
+
*
|
|
151
|
+
* What the map **summed** is the other field, and the two are not the same
|
|
152
|
+
* question: see {@link RegionReading.audiences}.
|
|
153
|
+
*/
|
|
154
|
+
readonly audienceId: AudienceId | null;
|
|
155
|
+
/**
|
|
156
|
+
* Every audience the rows this map summed named, deduplicated and in a stable
|
|
157
|
+
* order.
|
|
158
|
+
*
|
|
159
|
+
* The same census `PageReading.audiences` publishes over a window of tallies,
|
|
160
|
+
* and it answers the same question — *what was in the window?* — but it is
|
|
161
|
+
* **not** the same kind of fact (0297). A page reading of two audiences is
|
|
162
|
+
* read as neither, because adding two forms' node counters is one number
|
|
163
|
+
* about two pages. A region map of two audiences is read whole, because
|
|
164
|
+
* adding two forms' arrivals is one number about one deployment's readers:
|
|
165
|
+
* they are people, and a person who arrived arrived once whichever form they
|
|
166
|
+
* were served.
|
|
167
|
+
*
|
|
168
|
+
* So more than one member here is a **measurement and never a fault**: *this
|
|
169
|
+
* map is a sum over two of the forms you serve*. `[]` is a window whose rows
|
|
170
|
+
* named none, which is every window written before the column existed (0284)
|
|
171
|
+
* and every one a test builds by hand.
|
|
172
|
+
*
|
|
173
|
+
* It is deliberately not a proof of which form the map is of.
|
|
174
|
+
* {@link RegionReading.audienceId} is that, and it stays `null` on a map read
|
|
175
|
+
* whole however few audiences the rows named (0294) — because an `aud_` is a
|
|
176
|
+
* name the host chose for a predicate Loom never sees, and `aud_everyone` is
|
|
177
|
+
* a name for *everybody*. One member means one name was on the rows, not that
|
|
178
|
+
* one population was behind them.
|
|
179
|
+
*/
|
|
180
|
+
readonly audiences: readonly AudienceId[];
|
|
181
|
+
/** Buckets large enough to name, most-read first. */
|
|
182
|
+
readonly regions: readonly RegionBucket[];
|
|
183
|
+
/** What was too small to name, as a total that names nowhere. */
|
|
184
|
+
readonly withheld: {
|
|
185
|
+
readonly buckets: number;
|
|
186
|
+
readonly views: number;
|
|
187
|
+
};
|
|
188
|
+
/** Every view in the rows, named or withheld. A reading never loses one. */
|
|
189
|
+
readonly views: number;
|
|
190
|
+
};
|
|
191
|
+
export type RegionReadingOptions = {
|
|
192
|
+
/** Raised above {@link DEFAULT_REGION_FLOOR}; a smaller number is the default. */
|
|
193
|
+
readonly floor?: number | undefined;
|
|
194
|
+
};
|
|
195
|
+
/**
|
|
196
|
+
* Rows from the store, read as something a screen may show.
|
|
197
|
+
*
|
|
198
|
+
* **Grouped before it is suppressed, and the order matters.** Ten views of one
|
|
199
|
+
* revision and twenty of the next are thirty views of one country, which is a
|
|
200
|
+
* readership; suppressing each revision first would withhold both and report a
|
|
201
|
+
* map of nowhere. A caller asking about one revision filters at the store,
|
|
202
|
+
* where the filter belongs.
|
|
203
|
+
*
|
|
204
|
+
* **The unplaced bucket is never withheld**, however small it is. It names no
|
|
205
|
+
* place, so there is nobody in it to re-identify, and hiding it would mean a
|
|
206
|
+
* reading whose numbers do not add up to the number of views there were.
|
|
207
|
+
*
|
|
208
|
+
* **It sums across the audiences it was handed, and says which ones they
|
|
209
|
+
* were.** A page served in two forms counts each form's arrivals on its own row
|
|
210
|
+
* (0284), and both forms' readers are the same deployment's readers — a person
|
|
211
|
+
* who arrived arrived once, whichever form they were served — so a map of the
|
|
212
|
+
* window is the readership and not a collapse of two. The census is published
|
|
213
|
+
* on {@link RegionReading.audiences} so that a caller comparing two such maps
|
|
214
|
+
* can say what each was a sum over, and nothing is refused on it (0297).
|
|
215
|
+
*/
|
|
216
|
+
export declare const regionReadingOf: (rows: readonly StoredRegionCount[], options?: RegionReadingOptions) => RegionReading;
|
|
217
|
+
/**
|
|
218
|
+
* One revision's region rows, read as a map, without the caller writing the
|
|
219
|
+
* filter.
|
|
220
|
+
*
|
|
221
|
+
* The same shape and the same reason as `pageViewsFor` in
|
|
222
|
+
* [`page-views.ts`](page-views.ts): the matching is the part of every join in
|
|
223
|
+
* this subsystem that fails quietly when it is got wrong, and a comparison of
|
|
224
|
+
* two revisions' readerships is the first thing here that has to do it twice in
|
|
225
|
+
* one call. Reading one revision's map against another revision's rows would
|
|
226
|
+
* answer confidently and be about nothing.
|
|
227
|
+
*
|
|
228
|
+
* **Filtered before it is floored, which is the half that is not obvious.**
|
|
229
|
+
* {@link regionReadingOf} groups across whatever it is handed, because thirty
|
|
230
|
+
* views of one country spread over two revisions are a readership and
|
|
231
|
+
* suppressing each revision first would withhold both. A caller asking about
|
|
232
|
+
* one revision is asking a narrower question and gets a narrower answer: the
|
|
233
|
+
* floor bites harder per revision than it does across a deployment, so a quiet
|
|
234
|
+
* page reports more of itself as withheld. That is the floor working rather
|
|
235
|
+
* than a fault, and it is why a readership comparison is answerable on a page
|
|
236
|
+
* with traffic and says so on a page without.
|
|
237
|
+
*/
|
|
238
|
+
export type RegionReadingFor = {
|
|
239
|
+
/** The revision's own map, floored. */
|
|
240
|
+
readonly reading: RegionReading;
|
|
241
|
+
/**
|
|
242
|
+
* Rows for another tree or another revision, and ignored.
|
|
243
|
+
*
|
|
244
|
+
* Counting another revision's arrivals into this one's map is the mistake
|
|
245
|
+
* that would make a readership comparison compare a revision with itself.
|
|
246
|
+
*/
|
|
247
|
+
readonly foreign: number;
|
|
248
|
+
/**
|
|
249
|
+
* Rows for this revision in another audience, and ignored.
|
|
250
|
+
*
|
|
251
|
+
* A page served in two forms counts each form's arrivals on its own row
|
|
252
|
+
* (0284), and both forms' readers are real readers of the page — so this is
|
|
253
|
+
* neither foreign nor a doubled bucket. It is the other form's readership,
|
|
254
|
+
* which is a different map and not part of this one: a mix taken over both
|
|
255
|
+
* is one composition of two populations, and a comparison beside it would be
|
|
256
|
+
* comparing neither form with itself.
|
|
257
|
+
*/
|
|
258
|
+
readonly otherAudience: number;
|
|
259
|
+
/**
|
|
260
|
+
* Rows naming a region **and an audience** this revision already had a row
|
|
261
|
+
* for, beyond the first, every one of which was ignored.
|
|
262
|
+
*
|
|
263
|
+
* A store keeps one row per tree, revision, audience and region, so this
|
|
264
|
+
* cannot come out of one read — it happens when a caller concatenates two
|
|
265
|
+
* windows of rows, and the store's counts are already running totals rather
|
|
266
|
+
* than a window's. Adding them would double a bucket, which is the one error
|
|
267
|
+
* in this subsystem that cannot be undone afterwards (0158), so the first row
|
|
268
|
+
* stands and the fact is reported.
|
|
269
|
+
*
|
|
270
|
+
* **The audience is part of what makes two rows two rows**, and leaving it
|
|
271
|
+
* out was a quiet undercount (0297). A revision served in two forms (0263)
|
|
272
|
+
* has two rows for one country, one per form, and a map read whole of such a
|
|
273
|
+
* revision dropped the second as the first handed in twice: 60 views
|
|
274
|
+
* published where 460 arrived, with the loss reported as a count of
|
|
275
|
+
* duplicates nobody would read as an undercount. A form's own map is
|
|
276
|
+
* unaffected — the audience is picked before this, so region and audience key
|
|
277
|
+
* the same rows region alone did.
|
|
278
|
+
*/
|
|
279
|
+
readonly duplicated: number;
|
|
280
|
+
};
|
|
281
|
+
/**
|
|
282
|
+
* Pick one revision's region rows out of a set of them and read them.
|
|
283
|
+
*
|
|
284
|
+
* Linear in the rows, with one pass and one map.
|
|
285
|
+
*/
|
|
286
|
+
export declare const regionReadingFor: (where: RevisionOf, rows: readonly StoredRegionCount[], options?: RegionReadingOptions) => RegionReadingFor;
|
|
287
|
+
//# sourceMappingURL=region.d.ts.map
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { audiencesIn } from "./audiences.js";
|
|
3
|
+
/**
|
|
4
|
+
* Where readers are, as a counter and nothing else.
|
|
5
|
+
*
|
|
6
|
+
* A coarse region is the one fact about a reader that a deployment can know
|
|
7
|
+
* without the browser ever being told it is being measured: the request arrived
|
|
8
|
+
* from somewhere, and the platform in front of the application already wrote
|
|
9
|
+
* that down in a header. Nothing is added to a batch, nothing is asked of the
|
|
10
|
+
* page, and the address the region was read from is never stored.
|
|
11
|
+
*
|
|
12
|
+
* Three refusals hold the shape, and they are the design rather than caveats on
|
|
13
|
+
* it:
|
|
14
|
+
*
|
|
15
|
+
* - **It lands on a counter, never on a buffered batch.** A region beside a
|
|
16
|
+
* view key on a raw row is the beginning of a profile — one row saying *this
|
|
17
|
+
* page view came from here* — and the only thing stopping it becoming one
|
|
18
|
+
* would be that nobody got round to joining the two. So the region is counted
|
|
19
|
+
* at the door and the raw row never carries it.
|
|
20
|
+
* - **A bucket is reported only once it is too large to be a person.** A country
|
|
21
|
+
* with a handful of views in it is a reader, not a readership. The floor is a
|
|
22
|
+
* number this module owns, a deployment may raise it and may not lower it, and
|
|
23
|
+
* what it suppresses is still *counted* — a reading says how many views it is
|
|
24
|
+
* withholding, so the total stays true while the attribution does not exist.
|
|
25
|
+
* - **One page view is one view.** Counting deliveries instead would be the
|
|
26
|
+
* quiet failure: a reader who stays ten minutes posts a hundred batches, so a
|
|
27
|
+
* single person would clear any floor on their own and the protection would
|
|
28
|
+
* invert. A batch says whether it opened its page view, and only those count.
|
|
29
|
+
*
|
|
30
|
+
* The exactness is worth naming, because the per-node counters do not have it.
|
|
31
|
+
* `views` on a tally counts distinct page views inside a rollup window and is
|
|
32
|
+
* added to the next window's, so a view that straddles the boundary is counted
|
|
33
|
+
* twice (0147). A region view is counted once, at the moment a page view began,
|
|
34
|
+
* and is never recounted — so these numbers add across revisions, across trees
|
|
35
|
+
* and across months without drifting.
|
|
36
|
+
*/
|
|
37
|
+
/** The sentinel, before it is a region. The schema below is what makes it one. */
|
|
38
|
+
const UNKNOWN = "unknown";
|
|
39
|
+
/**
|
|
40
|
+
* A region nobody can name.
|
|
41
|
+
*
|
|
42
|
+
* A deployment behind a proxy that adds no such header, a request from a
|
|
43
|
+
* development machine, a header holding something that is not a country code —
|
|
44
|
+
* all of them are this, and it is a bucket rather than a dropped row. *We do
|
|
45
|
+
* not know where 40 of these views came from* is a fact about the measurement;
|
|
46
|
+
* silently keeping only the views that could be placed is a figure that looks
|
|
47
|
+
* complete and is not.
|
|
48
|
+
*
|
|
49
|
+
* Seven characters, so it can never collide with a two-letter code.
|
|
50
|
+
*/
|
|
51
|
+
export const UNKNOWN_REGION = UNKNOWN;
|
|
52
|
+
/** Two uppercase letters, which is what a country code is. */
|
|
53
|
+
export const regionPattern = /^[A-Z]{2}$/;
|
|
54
|
+
/**
|
|
55
|
+
* A country, or the admission that there is none.
|
|
56
|
+
*
|
|
57
|
+
* Deliberately no narrower. A subdivision or a city is the step from *where our
|
|
58
|
+
* readers are* to *who that reader was* — a city plus a count of two is a
|
|
59
|
+
* person with an address — and the header carrying one is sitting beside the
|
|
60
|
+
* header this reads. It is not read.
|
|
61
|
+
*
|
|
62
|
+
* Deliberately no wider either: the value becomes a column, and a column fed
|
|
63
|
+
* from a request header is a column a caller can write to. Two letters or the
|
|
64
|
+
* one sentinel is a closed set, so the worst a poisoned header can do is add to
|
|
65
|
+
* a bucket that already exists.
|
|
66
|
+
*/
|
|
67
|
+
export const readerRegionSchema = z
|
|
68
|
+
.union([z.literal(UNKNOWN), z.string().regex(regionPattern)])
|
|
69
|
+
.brand();
|
|
70
|
+
/**
|
|
71
|
+
* Read a region off whatever the platform wrote, and never fail.
|
|
72
|
+
*
|
|
73
|
+
* Trimmed and upper-cased because headers are written by whoever is in front of
|
|
74
|
+
* the application and casing is not a thing to have an opinion about. Anything
|
|
75
|
+
* that is not a country code — absent, empty, a city, a word, the Tor marker
|
|
76
|
+
* some platforms send — is unplaced rather than refused: this runs on the
|
|
77
|
+
* request path of the one public write endpoint, and a region that cannot be
|
|
78
|
+
* read is a bucket, not an error.
|
|
79
|
+
*/
|
|
80
|
+
export const readerRegionOf = (given) => {
|
|
81
|
+
if (given === null || given === undefined)
|
|
82
|
+
return UNKNOWN_REGION;
|
|
83
|
+
const code = given.trim().toUpperCase();
|
|
84
|
+
return regionPattern.test(code) ? code : UNKNOWN_REGION;
|
|
85
|
+
};
|
|
86
|
+
/**
|
|
87
|
+
* What one delivery adds, which is one view per page view it opened.
|
|
88
|
+
*
|
|
89
|
+
* **It is handed the openings rather than the delivery**, so that a region can
|
|
90
|
+
* only ever be a stamp on a page view somebody already counted. The walk that
|
|
91
|
+
* finds them, and the deduplication that makes a retried opening one arrival
|
|
92
|
+
* rather than two, is `openingsOf` in `page-views.ts` — shared deliberately,
|
|
93
|
+
* because two counters that each decided for themselves how many readers
|
|
94
|
+
* arrived would sooner or later disagree about it, and the disagreement would
|
|
95
|
+
* surface as a map whose numbers do not add up to the number of page views
|
|
96
|
+
* there were.
|
|
97
|
+
*
|
|
98
|
+
* A delivery that opened nothing adds nothing, and a sender that never says
|
|
99
|
+
* adds nothing at all — which is the honest answer for a batch synthesised on a
|
|
100
|
+
* server or replayed from a fixture, exactly as such a batch adds nothing to
|
|
101
|
+
* any view count.
|
|
102
|
+
*/
|
|
103
|
+
export const regionCountsOf = (openings, region) => openings.map(({ treeId, revision, views }) => ({ treeId, revision, region, views }));
|
|
104
|
+
/**
|
|
105
|
+
* The smallest a bucket may be before it is named.
|
|
106
|
+
*
|
|
107
|
+
* Twenty-five, and the number is a judgement rather than a derivation: it is
|
|
108
|
+
* low enough that a deployment with a few hundred readers sees its own map, and
|
|
109
|
+
* high enough that no bucket is one person, one household or one office. A
|
|
110
|
+
* deployment that wants more caution raises it.
|
|
111
|
+
*
|
|
112
|
+
* It is not lowerable, and that is the one place this subsystem overrides an
|
|
113
|
+
* operator. The floor is what makes the aggregate an aggregate; a deployment
|
|
114
|
+
* that could set it to one would be running a different product, and the
|
|
115
|
+
* difference would be invisible on the screen that showed the result.
|
|
116
|
+
*/
|
|
117
|
+
export const DEFAULT_REGION_FLOOR = 25;
|
|
118
|
+
/**
|
|
119
|
+
* The floor that will actually be used, given what somebody asked for.
|
|
120
|
+
*
|
|
121
|
+
* Raise-only, and anything that is not a whole number of views is the default —
|
|
122
|
+
* a floor read from configuration is read from a string somebody typed, and the
|
|
123
|
+
* direction to be wrong in is the cautious one.
|
|
124
|
+
*/
|
|
125
|
+
export const regionFloorOf = (asked) => asked === undefined || !Number.isInteger(asked) ? DEFAULT_REGION_FLOOR : Math.max(DEFAULT_REGION_FLOOR, asked);
|
|
126
|
+
/**
|
|
127
|
+
* Rows from the store, read as something a screen may show.
|
|
128
|
+
*
|
|
129
|
+
* **Grouped before it is suppressed, and the order matters.** Ten views of one
|
|
130
|
+
* revision and twenty of the next are thirty views of one country, which is a
|
|
131
|
+
* readership; suppressing each revision first would withhold both and report a
|
|
132
|
+
* map of nowhere. A caller asking about one revision filters at the store,
|
|
133
|
+
* where the filter belongs.
|
|
134
|
+
*
|
|
135
|
+
* **The unplaced bucket is never withheld**, however small it is. It names no
|
|
136
|
+
* place, so there is nobody in it to re-identify, and hiding it would mean a
|
|
137
|
+
* reading whose numbers do not add up to the number of views there were.
|
|
138
|
+
*
|
|
139
|
+
* **It sums across the audiences it was handed, and says which ones they
|
|
140
|
+
* were.** A page served in two forms counts each form's arrivals on its own row
|
|
141
|
+
* (0284), and both forms' readers are the same deployment's readers — a person
|
|
142
|
+
* who arrived arrived once, whichever form they were served — so a map of the
|
|
143
|
+
* window is the readership and not a collapse of two. The census is published
|
|
144
|
+
* on {@link RegionReading.audiences} so that a caller comparing two such maps
|
|
145
|
+
* can say what each was a sum over, and nothing is refused on it (0297).
|
|
146
|
+
*/
|
|
147
|
+
export const regionReadingOf = (rows, options = {}) => {
|
|
148
|
+
const floor = regionFloorOf(options.floor);
|
|
149
|
+
const grouped = new Map();
|
|
150
|
+
for (const row of rows) {
|
|
151
|
+
grouped.set(row.region, (grouped.get(row.region) ?? 0) + row.views);
|
|
152
|
+
}
|
|
153
|
+
const buckets = [...grouped.entries()].map(([region, views]) => ({ region, views }));
|
|
154
|
+
const nameable = (bucket) => bucket.region === UNKNOWN_REGION || bucket.views >= floor;
|
|
155
|
+
const named = buckets.filter(nameable);
|
|
156
|
+
const small = buckets.filter((bucket) => !nameable(bucket));
|
|
157
|
+
return {
|
|
158
|
+
floor,
|
|
159
|
+
audienceId: null,
|
|
160
|
+
audiences: audiencesIn(rows),
|
|
161
|
+
/** Most-read first, and by code when two are equal, so a screen does not reorder on a refresh. */
|
|
162
|
+
regions: named.sort((one, other) => other.views - one.views || one.region.localeCompare(other.region)),
|
|
163
|
+
withheld: {
|
|
164
|
+
buckets: small.length,
|
|
165
|
+
views: small.reduce((total, bucket) => total + bucket.views, 0),
|
|
166
|
+
},
|
|
167
|
+
views: buckets.reduce((total, bucket) => total + bucket.views, 0),
|
|
168
|
+
};
|
|
169
|
+
};
|
|
170
|
+
/**
|
|
171
|
+
* Pick one revision's region rows out of a set of them and read them.
|
|
172
|
+
*
|
|
173
|
+
* Linear in the rows, with one pass and one map.
|
|
174
|
+
*/
|
|
175
|
+
export const regionReadingFor = (where, rows, options = {}) => {
|
|
176
|
+
const here = rows.filter((row) => row.treeId === where.treeId && row.revision === where.revision);
|
|
177
|
+
const audience = where.audienceId ?? null;
|
|
178
|
+
const matching = audience === null ? here : here.filter((row) => row.audienceId === audience);
|
|
179
|
+
/**
|
|
180
|
+
* Keyed by the region **and** the audience, which is what the store keeps one
|
|
181
|
+
* row per (0284): two forms' arrivals in one country are two rows and one
|
|
182
|
+
* readership, and keying by the region alone dropped the second as a repeat
|
|
183
|
+
* of the first (0297).
|
|
184
|
+
*/
|
|
185
|
+
const first = new Map();
|
|
186
|
+
for (const row of matching) {
|
|
187
|
+
const bucket = `${row.region}\u0000${row.audienceId}`;
|
|
188
|
+
if (!first.has(bucket))
|
|
189
|
+
first.set(bucket, row);
|
|
190
|
+
}
|
|
191
|
+
return {
|
|
192
|
+
reading: { ...regionReadingOf([...first.values()], options), audienceId: audience },
|
|
193
|
+
foreign: rows.length - here.length,
|
|
194
|
+
otherAudience: here.length - matching.length,
|
|
195
|
+
duplicated: matching.length - first.size,
|
|
196
|
+
};
|
|
197
|
+
};
|
|
198
|
+
//# sourceMappingURL=region.js.map
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
import type { ExpiryOutcome } from "./expire.js";
|
|
2
|
+
import type { DeliveryRetention } from "./notice.js";
|
|
3
|
+
/**
|
|
4
|
+
* Whether the deployment keeps the retention ceiling it publishes to its
|
|
5
|
+
* readers.
|
|
6
|
+
*
|
|
7
|
+
* A notice tells the reader three things about a delivery's life: the age it is
|
|
8
|
+
* counted at and the age it is deleted at, which are this deployment's own
|
|
9
|
+
* numbers, and how often its sweep runs, which is a claim about a cron nobody
|
|
10
|
+
* here can see (0320, 0351). They make a ceiling — *gone within 31 days of
|
|
11
|
+
* arriving* — and a deployment that states a day and sweeps monthly publishes
|
|
12
|
+
* that sentence to every reader of its privacy page with nothing behind it.
|
|
13
|
+
*
|
|
14
|
+
* **The evidence is already in the sweep's own hands.** A run scans the table
|
|
15
|
+
* from its oldest end, so the age of the oldest delivery still there is a
|
|
16
|
+
* number every run has and none of them reported. If that age is past the
|
|
17
|
+
* ceiling, then a delivery existed that readers were told was gone — and it
|
|
18
|
+
* existed for however long the gap is, whatever this run then deletes.
|
|
19
|
+
*
|
|
20
|
+
* So the check costs no read, no column, no byte on any wire and nothing in a
|
|
21
|
+
* browser: it is a subtraction over what a sweep already looked at.
|
|
22
|
+
*
|
|
23
|
+
* **It is the expiry run's evidence, not the fold's** (0351). Until 5 November
|
|
24
|
+
* the fold was the deletion, so the run that counted a window was also the run
|
|
25
|
+
* whose scan proved when deliveries went; now counting and deleting are two
|
|
26
|
+
* operations with two windows, and the published ceiling is about the second.
|
|
27
|
+
* Handing this the fold's outcome would judge a promise about deletion against
|
|
28
|
+
* a figure that measures how far behind counting is — which on a healthy
|
|
29
|
+
* deployment is minutes, so the check would read *kept* while a broken expiry
|
|
30
|
+
* cron kept everything for ever.
|
|
31
|
+
*
|
|
32
|
+
* ## It is beside the notice and never inside it
|
|
33
|
+
*
|
|
34
|
+
* `collectionNoticeOf` is a pure function of a deployment's configuration and
|
|
35
|
+
* has to stay one (0313): a privacy page with a store and a clock behind it is
|
|
36
|
+
* a page that cannot render while the database is down, which is worse for a
|
|
37
|
+
* reader than a stated ceiling. The judgement therefore lives here, where a
|
|
38
|
+
* store and a clock are already in the room, and it is handed the same
|
|
39
|
+
* retention the notice publishes rather than a second derivation of it — a
|
|
40
|
+
* sweep that computed its own ceiling could clear a promise nobody made.
|
|
41
|
+
*
|
|
42
|
+
* ## What it refuses to judge
|
|
43
|
+
*
|
|
44
|
+
* Three of the five states answer *nothing is wrong* without asserting that
|
|
45
|
+
* anything is right, and each is a refusal rather than a gap: a deployment that
|
|
46
|
+
* stated no interval published no ceiling, a run that never reached the buffer
|
|
47
|
+
* saw no delivery, and a run that found nothing ripe has proved the promise
|
|
48
|
+
* holds without needing a figure at all.
|
|
49
|
+
*
|
|
50
|
+
* Pure, constant-time, and reaches no store, clock or DOM.
|
|
51
|
+
*/
|
|
52
|
+
/** How a published retention ceiling stood at the moment of one sweep. */
|
|
53
|
+
export type RetentionPromise =
|
|
54
|
+
/**
|
|
55
|
+
* The deployment stated no sweep interval, so its notice publishes no
|
|
56
|
+
* ceiling.
|
|
57
|
+
*
|
|
58
|
+
* There is nothing for a run to keep or break. The remedy is not a sweep's:
|
|
59
|
+
* an operator states the interval their cron actually runs on, and until they
|
|
60
|
+
* do their readers are told when a delivery ripens and nothing about when it
|
|
61
|
+
* goes.
|
|
62
|
+
*/
|
|
63
|
+
{
|
|
64
|
+
readonly state: "unpromised";
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* The run read no delivery, so nothing here says how old the oldest one is.
|
|
68
|
+
*
|
|
69
|
+
* Either it never reached the table — refused on its window, or the store was
|
|
70
|
+
* unavailable — or the one instant it needed could not be read. A table the
|
|
71
|
+
* sweep cannot see is a promise nothing can speak for, and the honest answer
|
|
72
|
+
* is silence rather than *kept*.
|
|
73
|
+
*/
|
|
74
|
+
| {
|
|
75
|
+
readonly state: "unread";
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Nothing in the table is old enough to delete, so nothing in it can be past
|
|
79
|
+
* the ceiling.
|
|
80
|
+
*
|
|
81
|
+
* The strongest of the three quiet answers and the only one that is a proof.
|
|
82
|
+
* A scan runs from the oldest end, so a run that found nothing expirable
|
|
83
|
+
* found every delivery younger than the kept window — and the ceiling is that
|
|
84
|
+
* window plus a sweep, which is longer. An empty table lands here too, for
|
|
85
|
+
* the same reason and with nothing waiting.
|
|
86
|
+
*/
|
|
87
|
+
| {
|
|
88
|
+
readonly state: "unripe";
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* The oldest delivery in the buffer is within the ceiling the notice
|
|
92
|
+
* publishes.
|
|
93
|
+
*
|
|
94
|
+
* Both figures travel, because the sentence an operator wants is the
|
|
95
|
+
* comparison and not the verdict: *the oldest here is twelve minutes old and
|
|
96
|
+
* your readers are told seventy*.
|
|
97
|
+
*/
|
|
98
|
+
| {
|
|
99
|
+
readonly state: "kept";
|
|
100
|
+
/** How old the oldest delivery still in the table was, in milliseconds. */
|
|
101
|
+
readonly oldestMs: number;
|
|
102
|
+
/** The ceiling the notice publishes: the later of the two windows plus one sweep. */
|
|
103
|
+
readonly goneWithinMs: number;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* A delivery is older than the ceiling the notice publishes, so that sentence
|
|
107
|
+
* is false and was false for `byMs` before this run.
|
|
108
|
+
*
|
|
109
|
+
* The deployment is either sweeping less often than it stated or not sweeping
|
|
110
|
+
* at all, and the two are the same fault from here. Raising the stated
|
|
111
|
+
* interval makes the published promise true and weaker; sweeping on the
|
|
112
|
+
* interval already stated makes it true and keeps it — and that choice is an
|
|
113
|
+
* operator's, so this names the gap rather than a remedy.
|
|
114
|
+
*/
|
|
115
|
+
| {
|
|
116
|
+
readonly state: "broken";
|
|
117
|
+
readonly oldestMs: number;
|
|
118
|
+
readonly goneWithinMs: number;
|
|
119
|
+
/** How far past the ceiling the oldest delivery is. */
|
|
120
|
+
readonly byMs: number;
|
|
121
|
+
/**
|
|
122
|
+
* Whether what is holding the oldest delivery is that no fold has counted
|
|
123
|
+
* it (`expire.ts`).
|
|
124
|
+
*
|
|
125
|
+
* The gap is real either way and this does not soften it — a delivery
|
|
126
|
+
* readers were told was gone is still there. What it does is name the
|
|
127
|
+
* remedy, which in this one case is not the expiry sweep's: nothing may
|
|
128
|
+
* delete an uncounted delivery, so a deployment whose collection has
|
|
129
|
+
* stopped breaks its retention promise by not counting, and running the
|
|
130
|
+
* deletion more often would change nothing.
|
|
131
|
+
*/
|
|
132
|
+
readonly uncounted: boolean;
|
|
133
|
+
};
|
|
134
|
+
/**
|
|
135
|
+
* Judge one expiry sweep's own evidence against the ceiling its deployment
|
|
136
|
+
* publishes.
|
|
137
|
+
*
|
|
138
|
+
* The retention is taken whole — the same `Pick` of the notice the reader's
|
|
139
|
+
* sentence is built from (0320) — so the ceiling judged here is the ceiling
|
|
140
|
+
* published, by construction rather than by a reviewer.
|
|
141
|
+
*
|
|
142
|
+
* **An unstated interval wins over everything else**, including a buffer months
|
|
143
|
+
* behind. It is not that the buffer is fine; it is that no ceiling was
|
|
144
|
+
* published, so a run has no claim of its deployment's to measure. The operator
|
|
145
|
+
* hears about an unstated schedule from the setting, which is where the remedy
|
|
146
|
+
* is.
|
|
147
|
+
*
|
|
148
|
+
* **A delivery received in the future is kept, by the same subtraction rather
|
|
149
|
+
* than by a special case** — a negative age is never longer than a positive
|
|
150
|
+
* ceiling, which is how the stall check answers a clock that disagrees with
|
|
151
|
+
* itself (0274).
|
|
152
|
+
*/
|
|
153
|
+
export declare const retentionPromiseOf: (outcome: ExpiryOutcome, retention: DeliveryRetention) => RetentionPromise;
|
|
154
|
+
/**
|
|
155
|
+
* One line for the operator who runs the sweep, because they are the only
|
|
156
|
+
* person who can close the gap.
|
|
157
|
+
*
|
|
158
|
+
* Milliseconds, as the settings an operator typed are in: a line that rounded
|
|
159
|
+
* to minutes would not tell somebody who wrote an interval in the wrong units
|
|
160
|
+
* which units it wanted.
|
|
161
|
+
*/
|
|
162
|
+
export declare const describeRetentionPromise: (promise: RetentionPromise) => string;
|
|
163
|
+
//# sourceMappingURL=retention.d.ts.map
|