@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,389 @@
|
|
|
1
|
+
import type { ReaderSignalOptions } from "./broadcast.js";
|
|
2
|
+
import { type ReaderSignal, type ReaderSignalBatch, type ReaderSignalKind } from "./signal.js";
|
|
3
|
+
/**
|
|
4
|
+
* What a published page reports, written for the people it reports about.
|
|
5
|
+
*
|
|
6
|
+
* Every other reading in this subsystem answers a deployment's question. This
|
|
7
|
+
* is the one that answers a reader's, and it is the half of the argument that
|
|
8
|
+
* had nothing behind it: Loom exists so that a change to a page can be
|
|
9
|
+
* inspected, attributed and undone, and reader measurement that could not be
|
|
10
|
+
* explained to the person being measured would contradict the whole premise.
|
|
11
|
+
* Every competitor in this space collects more and explains less; the
|
|
12
|
+
* explaining has to be something a deployment can publish, not a paragraph in
|
|
13
|
+
* this repository.
|
|
14
|
+
*
|
|
15
|
+
* So this is a value rather than a page: a structure a deployment's privacy
|
|
16
|
+
* page, portal or consent surface can print, derived from the configuration its
|
|
17
|
+
* own pages are broadcast with.
|
|
18
|
+
*
|
|
19
|
+
* ## Why it is derived and not written
|
|
20
|
+
*
|
|
21
|
+
* A hand-written list of what a product collects is right on the day it is
|
|
22
|
+
* written. This one cannot drift from the payload, and it is the type system
|
|
23
|
+
* that holds it rather than a reviewer: {@link DELIVERY_FIELDS} and
|
|
24
|
+
* {@link SIGNAL_FIELDS} are keyed by the schema's own fields through
|
|
25
|
+
* `keyof Required<…>`, so **a field added to a batch without a sentence here
|
|
26
|
+
* does not compile.** `notice.test.ts` holds the other end, which a type cannot
|
|
27
|
+
* reach: it drives the real broadcaster over a real page and fails if a kind or
|
|
28
|
+
* a field arrives that this does not name.
|
|
29
|
+
*
|
|
30
|
+
* ## It is a ceiling, and never an understatement
|
|
31
|
+
*
|
|
32
|
+
* The notice names everything the configuration permits. A deployment that
|
|
33
|
+
* narrows `types` collects about fewer parts than this says, and one that turns
|
|
34
|
+
* `within` off carries no ancestry on the three delegated kinds. Both are
|
|
35
|
+
* published here as though they were on.
|
|
36
|
+
*
|
|
37
|
+
* That is deliberate in one direction only. A disclosure that overstates costs
|
|
38
|
+
* a reader nothing and a deployment a little credit; one that understates is
|
|
39
|
+
* the failure this module exists to make impossible. It also keeps the notice
|
|
40
|
+
* stable: a ceiling changes when the vocabulary or the deployment's own three
|
|
41
|
+
* numbers change, where a floor would have to be republished every time
|
|
42
|
+
* somebody added a primitive type to a list.
|
|
43
|
+
*
|
|
44
|
+
* ## What it is not
|
|
45
|
+
*
|
|
46
|
+
* **Not a consent gate and not a banner.** There is nothing here to consent to:
|
|
47
|
+
* a signal is anonymous and node-shaped, correlation is scoped to one page view
|
|
48
|
+
* by a key that never persists, and neither is configurable
|
|
49
|
+
* ([0146](../../decisions/0146-a-reader-signal-stays-anonymous-and-a-funnel-is-correlated-inside-one-page-view.md)).
|
|
50
|
+
* A notice says what is collected; the rules say it cannot be about a person.
|
|
51
|
+
* Per-reader identity is parked, and nothing here assumes it ever arrives or
|
|
52
|
+
* builds toward it — what a gate would need is a recorded decision, which is a
|
|
53
|
+
* different artefact from this one.
|
|
54
|
+
*
|
|
55
|
+
* **Not a reading.** It touches no store, no clock and no counter. Three
|
|
56
|
+
* numbers come from the deployment's own configuration — the window a
|
|
57
|
+
* delivery ripens at, the floor under a published country, and how often its
|
|
58
|
+
* sweep runs (0320) — and everything else is the vocabulary.
|
|
59
|
+
*
|
|
60
|
+
* ## The voice
|
|
61
|
+
*
|
|
62
|
+
* Every sentence in this module is addressed to a reader of the page, because
|
|
63
|
+
* that is who ends up reading them: *your address is never stored*, not *the
|
|
64
|
+
* reader's address is never stored*. It is the one module in `src/signals/`
|
|
65
|
+
* that speaks to anybody.
|
|
66
|
+
*/
|
|
67
|
+
/** What one field of a delivery is about. */
|
|
68
|
+
export type FieldSubject =
|
|
69
|
+
/** The part of the page the observation is about. */
|
|
70
|
+
"part"
|
|
71
|
+
/** Which page, which revision of it, and which form was served. */
|
|
72
|
+
| "page"
|
|
73
|
+
/** What was observed about the part — when, how long, open or closed. */
|
|
74
|
+
| "observation"
|
|
75
|
+
/**
|
|
76
|
+
* The one visit the delivery belongs to.
|
|
77
|
+
*
|
|
78
|
+
* The narrowest scope anything here is correlated at, and the only one about
|
|
79
|
+
* a visit rather than about a page (0146).
|
|
80
|
+
*/
|
|
81
|
+
| "page-view"
|
|
82
|
+
/** The delivery itself — when it was sent, and what it carried. */
|
|
83
|
+
| "delivery";
|
|
84
|
+
/**
|
|
85
|
+
* The closed set, for a surface grouping a notice by what its fields are about.
|
|
86
|
+
*
|
|
87
|
+
* **There is deliberately no member for the reader.** Every field of every
|
|
88
|
+
* batch is about one of these five things, which is rule 1 stated as a type
|
|
89
|
+
* rather than as a sentence: a field that needed a sixth member would be a
|
|
90
|
+
* field about a person, and adding one is a decision record and not a
|
|
91
|
+
* judgement call inside a pull request.
|
|
92
|
+
*/
|
|
93
|
+
export declare const FIELD_SUBJECTS: readonly FieldSubject[];
|
|
94
|
+
/** One line per subject, addressed to the reader, for a surface grouping a notice. */
|
|
95
|
+
export declare const describeFieldSubject: (subject: FieldSubject) => string;
|
|
96
|
+
/** One field of a payload, and what it says. */
|
|
97
|
+
export type CollectedField = {
|
|
98
|
+
/** The field's name in the delivery, which is what a reader comparing this to a payload sees. */
|
|
99
|
+
readonly field: string;
|
|
100
|
+
/** What it is about. */
|
|
101
|
+
readonly subject: FieldSubject;
|
|
102
|
+
/** One sentence, addressed to the reader. */
|
|
103
|
+
readonly says: string;
|
|
104
|
+
};
|
|
105
|
+
/** A field as the tables below hold it, before its name is read off the key. */
|
|
106
|
+
type FieldNote = Omit<CollectedField, "field">;
|
|
107
|
+
/**
|
|
108
|
+
* Every field of one shape, keyed by the shape's own fields.
|
|
109
|
+
*
|
|
110
|
+
* `Required` is what makes an optional field — `within`, `view`, `audience`,
|
|
111
|
+
* `first` — as mandatory to describe as any other. A reader is owed a sentence
|
|
112
|
+
* about a field that is sometimes there.
|
|
113
|
+
*/
|
|
114
|
+
type FieldsOf<Shape> = {
|
|
115
|
+
readonly [Field in keyof Required<Shape>]: FieldNote;
|
|
116
|
+
};
|
|
117
|
+
/**
|
|
118
|
+
* Every kind's fields.
|
|
119
|
+
*
|
|
120
|
+
* Spread from {@link ADDRESS_FIELDS} rather than written five times, with the
|
|
121
|
+
* per-kind annotation doing the checking: the three shared entries plus
|
|
122
|
+
* whatever that kind adds has to be exactly the fields the schema gives it.
|
|
123
|
+
*/
|
|
124
|
+
export declare const SIGNAL_FIELDS: {
|
|
125
|
+
readonly [Kind in ReaderSignalKind]: FieldsOf<Extract<ReaderSignal, {
|
|
126
|
+
kind: Kind;
|
|
127
|
+
}>>;
|
|
128
|
+
};
|
|
129
|
+
/** What travels with a delivery, whatever observations are in it. */
|
|
130
|
+
export declare const DELIVERY_FIELDS: FieldsOf<ReaderSignalBatch>;
|
|
131
|
+
/** Something a reader signal never carries, whatever a deployment configures. */
|
|
132
|
+
export type Refusal =
|
|
133
|
+
/**
|
|
134
|
+
* No identifier for a person or a device, and nothing standing in for one.
|
|
135
|
+
*
|
|
136
|
+
* The first clause of rule 1. The second half of the sentence is the half
|
|
137
|
+
* that matters to somebody who has read a privacy policy before: an
|
|
138
|
+
* identifier nobody set is still an identifier.
|
|
139
|
+
*/
|
|
140
|
+
"no-identifier"
|
|
141
|
+
/** No signature derived from a device, a browser or its settings. */
|
|
142
|
+
| "no-fingerprint"
|
|
143
|
+
/** Nothing the page said to you and nothing you said to it. */
|
|
144
|
+
| "no-content"
|
|
145
|
+
/** No cursor, no scroll trace, no recording. */
|
|
146
|
+
| "no-pointer-path"
|
|
147
|
+
/** Nothing that joins one visit to another. */
|
|
148
|
+
| "no-stitching"
|
|
149
|
+
/** Nothing derived from your address outlives the request it arrived on. */
|
|
150
|
+
| "no-address";
|
|
151
|
+
/** The closed set, for a surface listing what is refused. */
|
|
152
|
+
export declare const REFUSALS: readonly Refusal[];
|
|
153
|
+
/** One line per refusal, addressed to the reader. */
|
|
154
|
+
export declare const describeRefusal: (refusal: Refusal) => string;
|
|
155
|
+
/** Where a deployment counts its readers from, or that it does not. */
|
|
156
|
+
export type RegionNotice = {
|
|
157
|
+
/**
|
|
158
|
+
* The page views a country needs before it is published at all, or `null`
|
|
159
|
+
* where no country is read.
|
|
160
|
+
*
|
|
161
|
+
* `null` is *nothing about where you are is read*, which is a different
|
|
162
|
+
* sentence from *your country is counted and will not be published until
|
|
163
|
+
* enough others share it* — and the difference is the whole of what a floor
|
|
164
|
+
* is for. A country with a handful of views in it is a person (§7).
|
|
165
|
+
*/
|
|
166
|
+
readonly floor: number | null;
|
|
167
|
+
};
|
|
168
|
+
/** One or two sentences about where readers are counted from, addressed to the reader. */
|
|
169
|
+
export declare const describeRegionNotice: (notice: RegionNotice) => string;
|
|
170
|
+
/**
|
|
171
|
+
* How often the deployment's own sweep runs, or that it has not said.
|
|
172
|
+
*
|
|
173
|
+
* The one thing a reader of {@link CollectionNotice.bufferMs} could not find
|
|
174
|
+
* out. `bufferMs` is the age at which a delivery becomes *ripe* — ready to be
|
|
175
|
+
* counted into the totals and deleted — and nothing in `src/signals/` deletes
|
|
176
|
+
* it: a host calls {@link collectReaderSignals} from a cron, a deploy hook or
|
|
177
|
+
* by hand (0146, 0158). So a deployment that never scheduled the sweep keeps
|
|
178
|
+
* every delivery for ever while its notice names an hour, and *a delivery is
|
|
179
|
+
* kept until it is 60 minutes old* was read by somebody with no way of hearing
|
|
180
|
+
* *…or indefinitely*.
|
|
181
|
+
*
|
|
182
|
+
* The deployment is the only party that knows how often it sweeps, so it states
|
|
183
|
+
* it — the shape `CollectionSchedule` already takes for the operator's half of
|
|
184
|
+
* the same fact
|
|
185
|
+
* ([0274](../../decisions/0274-a-page-view-row-says-when-the-fold-last-touched-it-and-a-stall-is-judged-against-a-schedule-the-deployment-hands-in.md)).
|
|
186
|
+
* A framework that guessed an interval would publish a ceiling nobody promised.
|
|
187
|
+
*
|
|
188
|
+
* **Two states rather than a nullable number**, because the ceiling has to be
|
|
189
|
+
* unreachable where no schedule was stated: a surface cannot print *gone within
|
|
190
|
+
* 70 minutes* on a deployment that promised nothing, which is the one way this
|
|
191
|
+
* field could make a notice overstate.
|
|
192
|
+
*/
|
|
193
|
+
export type SweepNotice = {
|
|
194
|
+
readonly state: "stated";
|
|
195
|
+
/** The longest the deployment lets pass between sweeps, as it stated it. */
|
|
196
|
+
readonly everyMs: number;
|
|
197
|
+
/**
|
|
198
|
+
* The longest a delivery can live: the later of its two windows, plus one
|
|
199
|
+
* sweep interval.
|
|
200
|
+
*
|
|
201
|
+
* A sweep adds because a delivery does not go the instant it is eligible
|
|
202
|
+
* but at the next run, which is the arithmetic
|
|
203
|
+
* `CollectionSchedule.foldsWithinMs` spells out for the operator's half
|
|
204
|
+
* of this question (0274) — so **this is the number the retention check
|
|
205
|
+
* is given**, and a deployment states the interval once rather than
|
|
206
|
+
* keeping a reader's ceiling and an operator's threshold in step by hand.
|
|
207
|
+
*
|
|
208
|
+
* **The later of the two windows rather than their sum** (0351). A
|
|
209
|
+
* delivery is counted once it is `bufferMs` old and deleted once it is
|
|
210
|
+
* `keptMs` old, and both are measured from the same instant — the moment
|
|
211
|
+
* it arrived — so the second condition is met at the later of the two
|
|
212
|
+
* ages, not after one window has elapsed and then the other. Where the
|
|
213
|
+
* kept window is the shorter of the two, which is an odd but legal
|
|
214
|
+
* configuration, the delivery still has to be counted before it may go,
|
|
215
|
+
* and the maximum says exactly that.
|
|
216
|
+
*/
|
|
217
|
+
readonly goneWithinMs: number;
|
|
218
|
+
}
|
|
219
|
+
/** Nothing was stated, so nothing here says when a ripe delivery actually goes. */
|
|
220
|
+
| {
|
|
221
|
+
readonly state: "unstated";
|
|
222
|
+
};
|
|
223
|
+
/** What a published page reports, and what it refuses to. */
|
|
224
|
+
export type CollectionNotice = {
|
|
225
|
+
/** The kinds this configuration broadcasts, in the vocabulary's order. */
|
|
226
|
+
readonly collects: readonly CollectedKind[];
|
|
227
|
+
/** What travels with every delivery. */
|
|
228
|
+
readonly delivery: readonly CollectedField[];
|
|
229
|
+
/** What is never collected, whatever else is configured. */
|
|
230
|
+
readonly refuses: readonly Refusal[];
|
|
231
|
+
/** Where readers are counted from, or that they are not. */
|
|
232
|
+
readonly region: RegionNotice;
|
|
233
|
+
/**
|
|
234
|
+
* How long a delivery waits before it is counted into the totals, in
|
|
235
|
+
* milliseconds.
|
|
236
|
+
*
|
|
237
|
+
* The deployment's own number (`collect.ts`). **It was the bound on the life
|
|
238
|
+
* of the page-view key and is not any more** (0351): a counted delivery used
|
|
239
|
+
* to be deleted in the same operation, and is now kept for
|
|
240
|
+
* {@link CollectionNotice.keptMs}. **The framework cannot promise the moment
|
|
241
|
+
* either sweep runs**, because a host schedules them: this is the age at
|
|
242
|
+
* which a delivery becomes ripe, not a guarantee about when the next run
|
|
243
|
+
* happens. What the deployment itself promises about that is
|
|
244
|
+
* {@link CollectionNotice.sweep}, and {@link describeBuffer} says all three
|
|
245
|
+
* together.
|
|
246
|
+
*/
|
|
247
|
+
readonly bufferMs: number;
|
|
248
|
+
/**
|
|
249
|
+
* How long a delivery itself is kept, measured from when it arrived, in
|
|
250
|
+
* milliseconds.
|
|
251
|
+
*
|
|
252
|
+
* The honest bound on the life of the page-view key, and the number that
|
|
253
|
+
* makes this notice true since 5 November: individual deliveries are kept —
|
|
254
|
+
* thirty days by default — so that a deployment can look at them rather than
|
|
255
|
+
* only at counters (0349), and a notice that went on saying a delivery was
|
|
256
|
+
* deleted an hour after it arrived would be telling every reader of a privacy
|
|
257
|
+
* page something the deployment had stopped doing.
|
|
258
|
+
*
|
|
259
|
+
* Longer than {@link CollectionNotice.bufferMs} on any ordinary
|
|
260
|
+
* configuration, and the ceiling is taken over both rather than off this one,
|
|
261
|
+
* because a delivery is never deleted before it is counted whichever of the
|
|
262
|
+
* two windows is shorter (`expire.ts`).
|
|
263
|
+
*/
|
|
264
|
+
readonly keptMs: number;
|
|
265
|
+
/**
|
|
266
|
+
* How often this deployment sweeps, where it has stated it.
|
|
267
|
+
*
|
|
268
|
+
* The half of retention that is not the framework's to promise, and the half
|
|
269
|
+
* a reader of the two windows alone would assume. {@link describeBuffer}
|
|
270
|
+
* takes them together for that reason: an age with no sweep beside it is a
|
|
271
|
+
* sentence that reads like a deletion and is not one.
|
|
272
|
+
*
|
|
273
|
+
* **One stated interval covers both sweeps**, because a deployment runs them
|
|
274
|
+
* from one place — counting and then expiring, in that order, in one cron
|
|
275
|
+
* route (0351). A deployment that ran them on two schedules would be stating
|
|
276
|
+
* the longer of the two here, which is what the ceiling needs.
|
|
277
|
+
*/
|
|
278
|
+
readonly sweep: SweepNotice;
|
|
279
|
+
};
|
|
280
|
+
/** One kind of observation, with the fields it carries. */
|
|
281
|
+
export type CollectedKind = {
|
|
282
|
+
readonly kind: ReaderSignalKind;
|
|
283
|
+
/** What the page observed, addressed to the reader. */
|
|
284
|
+
readonly observes: string;
|
|
285
|
+
/** Every field that kind carries, including the ones it sometimes omits. */
|
|
286
|
+
readonly carries: readonly CollectedField[];
|
|
287
|
+
};
|
|
288
|
+
/**
|
|
289
|
+
* Every part of how long a delivery lives: the age it is counted at, the age it
|
|
290
|
+
* is deleted at, and how often the deployment's sweep runs.
|
|
291
|
+
*
|
|
292
|
+
* A `Pick` of the notice rather than three arguments, so that the sentence
|
|
293
|
+
* cannot be built from some of them. The ripeness age alone reads as a deletion
|
|
294
|
+
* and is not one — and since 5 November it is not even the deletion's age
|
|
295
|
+
* (0351).
|
|
296
|
+
*/
|
|
297
|
+
export type DeliveryRetention = Pick<CollectionNotice, "bufferMs" | "keptMs" | "sweep">;
|
|
298
|
+
/**
|
|
299
|
+
* How long a delivery lives, addressed to the reader.
|
|
300
|
+
*
|
|
301
|
+
* It takes the retention whole, because the two ages are the halves the
|
|
302
|
+
* framework knows and the sweep is the half it cannot promise, and a notice
|
|
303
|
+
* that published an age without the sweep said *a delivery is kept until it is
|
|
304
|
+
* 60 minutes old* to a reader who had no way of hearing *…or for ever, if
|
|
305
|
+
* nobody runs the sweep*. Where a schedule was stated the sentence ends on a
|
|
306
|
+
* ceiling a reader can hold the deployment to; where none was, it says that in
|
|
307
|
+
* as many words rather than leaving the ages to be read as a promise.
|
|
308
|
+
*
|
|
309
|
+
* **Two ages since 5 November, and saying one of them would be the lie** (0349,
|
|
310
|
+
* 0351). A delivery is counted at the first age and deleted at the second, and
|
|
311
|
+
* the sentence is explicit about what the gap is for: so that the deployment
|
|
312
|
+
* can look at the deliveries behind its totals. A reader told only *counted
|
|
313
|
+
* into totals* would reasonably assume the delivery was gone.
|
|
314
|
+
*/
|
|
315
|
+
export declare const describeBuffer: (retention: DeliveryRetention) => string;
|
|
316
|
+
/** The configuration a notice is of. */
|
|
317
|
+
export type NoticeRequest = {
|
|
318
|
+
/**
|
|
319
|
+
* The options the page is broadcast with — the same object, so that a notice
|
|
320
|
+
* and the page it is about cannot disagree about which kinds are reported.
|
|
321
|
+
*
|
|
322
|
+
* Only `kinds` is read. `types` and `within` narrow collection below what the
|
|
323
|
+
* notice says, which is the ceiling rule above.
|
|
324
|
+
*/
|
|
325
|
+
readonly page?: Pick<ReaderSignalOptions, "kinds">;
|
|
326
|
+
/**
|
|
327
|
+
* The window the deployment collects on, from its own `CollectionRequest`
|
|
328
|
+
* (`collect.ts`). The default when absent.
|
|
329
|
+
*
|
|
330
|
+
* Reported as given rather than clamped: `collect.ts` is what refuses a
|
|
331
|
+
* window below its minimum, and a notice that silently reported a different
|
|
332
|
+
* number from the one a deployment configured would be a second rule about
|
|
333
|
+
* one setting.
|
|
334
|
+
*/
|
|
335
|
+
readonly windowMs?: number;
|
|
336
|
+
/**
|
|
337
|
+
* The region counting this deployment's intake does, where it does any.
|
|
338
|
+
*
|
|
339
|
+
* Absent is *no country is read*, which is the default: reading one is
|
|
340
|
+
* something an intake is configured to do (§7). A floor below the published
|
|
341
|
+
* minimum is raised to it, by the same helper the region map itself uses.
|
|
342
|
+
*/
|
|
343
|
+
readonly region?: {
|
|
344
|
+
readonly floor?: number | undefined;
|
|
345
|
+
};
|
|
346
|
+
/**
|
|
347
|
+
* How often this deployment's sweep runs, where it has stated it.
|
|
348
|
+
*
|
|
349
|
+
* Absent is *nothing is stated*, which is the honest default: nothing in this
|
|
350
|
+
* subsystem schedules a sweep, so a notice that assumed one would publish a
|
|
351
|
+
* ceiling no deployment promised. A value that is not a positive, finite
|
|
352
|
+
* number of milliseconds is read the same way — the notice may always
|
|
353
|
+
* promise a reader less than the deployment knows and may never promise more,
|
|
354
|
+
* and the operator-facing half, where a value that could not be read is said
|
|
355
|
+
* out loud, is a deployment's own settings (0317).
|
|
356
|
+
*/
|
|
357
|
+
readonly sweep?: {
|
|
358
|
+
readonly everyMs: number;
|
|
359
|
+
};
|
|
360
|
+
/**
|
|
361
|
+
* The window this deployment keeps individual deliveries for, from its own
|
|
362
|
+
* `ExpiryRequest` (`expire.ts`). The default when absent.
|
|
363
|
+
*
|
|
364
|
+
* Reported as given rather than clamped, as the collection window is and for
|
|
365
|
+
* the same reason: `expire.ts` is what refuses a window below its minimum.
|
|
366
|
+
*
|
|
367
|
+
* **Absent is the default rather than *nothing is kept*,** which is the one
|
|
368
|
+
* place this field differs in spirit from the sweep beside it. A deployment
|
|
369
|
+
* that calls the expiry sweep with no window gets thirty days (0349), so a
|
|
370
|
+
* notice that read an absent setting as *deleted the moment it is counted*
|
|
371
|
+
* would understate what is kept — and this module's standing rule is that it
|
|
372
|
+
* may overstate what is collected and may never overstate what is deleted.
|
|
373
|
+
*/
|
|
374
|
+
readonly keptMs?: number;
|
|
375
|
+
};
|
|
376
|
+
/**
|
|
377
|
+
* What a page broadcast with these options reports, as a deployment may publish
|
|
378
|
+
* it.
|
|
379
|
+
*
|
|
380
|
+
* Pure, and allocation-per-call: no store, no clock, no DOM.
|
|
381
|
+
*
|
|
382
|
+
* The kinds come out in the vocabulary's order and each appears once, whatever
|
|
383
|
+
* order a configuration names them in and however often — a notice is read by
|
|
384
|
+
* somebody who did not write the configuration, and *dwelled, dwelled, viewed*
|
|
385
|
+
* is a leak of how the options were typed rather than a fact about the page.
|
|
386
|
+
*/
|
|
387
|
+
export declare const collectionNoticeOf: (request?: NoticeRequest) => CollectionNotice;
|
|
388
|
+
export {};
|
|
389
|
+
//# sourceMappingURL=notice.d.ts.map
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
import { everyMemberOf } from "../closed-set.js";
|
|
2
|
+
import { DEFAULT_READER_SIGNAL_WINDOW_MS } from "./collect.js";
|
|
3
|
+
import { DEFAULT_READER_EVENT_RETENTION_MS } from "./expire.js";
|
|
4
|
+
import { regionFloorOf } from "./region.js";
|
|
5
|
+
import { READER_SIGNAL_KINDS, } from "./signal.js";
|
|
6
|
+
/**
|
|
7
|
+
* The closed set, for a surface grouping a notice by what its fields are about.
|
|
8
|
+
*
|
|
9
|
+
* **There is deliberately no member for the reader.** Every field of every
|
|
10
|
+
* batch is about one of these five things, which is rule 1 stated as a type
|
|
11
|
+
* rather than as a sentence: a field that needed a sixth member would be a
|
|
12
|
+
* field about a person, and adding one is a decision record and not a
|
|
13
|
+
* judgement call inside a pull request.
|
|
14
|
+
*/
|
|
15
|
+
export const FIELD_SUBJECTS = everyMemberOf()([
|
|
16
|
+
"part",
|
|
17
|
+
"page",
|
|
18
|
+
"observation",
|
|
19
|
+
"page-view",
|
|
20
|
+
"delivery",
|
|
21
|
+
]);
|
|
22
|
+
/** One line per subject, addressed to the reader, for a surface grouping a notice. */
|
|
23
|
+
export const describeFieldSubject = (subject) => {
|
|
24
|
+
switch (subject) {
|
|
25
|
+
case "part":
|
|
26
|
+
return "which part of the page it is about";
|
|
27
|
+
case "page":
|
|
28
|
+
return "which page you were reading, and which version of it";
|
|
29
|
+
case "observation":
|
|
30
|
+
return "what was observed about that part";
|
|
31
|
+
case "page-view":
|
|
32
|
+
return "this one visit to this one page, and nothing outside it";
|
|
33
|
+
case "delivery":
|
|
34
|
+
return "the delivery itself";
|
|
35
|
+
}
|
|
36
|
+
};
|
|
37
|
+
const fieldsOf = (table) => Object.entries(table).map(([field, note]) => ({ field, ...note }));
|
|
38
|
+
/** The three fields every kind carries: which kind it is, and which part it is about. */
|
|
39
|
+
const ADDRESS_FIELDS = {
|
|
40
|
+
kind: {
|
|
41
|
+
subject: "observation",
|
|
42
|
+
says: "which of the five kinds of observation this is, and nothing beyond the five",
|
|
43
|
+
},
|
|
44
|
+
nodeId: {
|
|
45
|
+
subject: "part",
|
|
46
|
+
says: "which part of the page this is about, as the page's own name for that part",
|
|
47
|
+
},
|
|
48
|
+
type: {
|
|
49
|
+
subject: "part",
|
|
50
|
+
says: "what kind of part it is — a section, a card, a link — and never what it says",
|
|
51
|
+
},
|
|
52
|
+
};
|
|
53
|
+
const AT = {
|
|
54
|
+
subject: "observation",
|
|
55
|
+
says: "when it happened, to the millisecond, by your browser's clock",
|
|
56
|
+
};
|
|
57
|
+
const WITHIN = {
|
|
58
|
+
subject: "part",
|
|
59
|
+
says: "the parts of the page it happened inside, named the same way — so that a press can be counted" +
|
|
60
|
+
" against the section it was in and not only against the button",
|
|
61
|
+
};
|
|
62
|
+
/**
|
|
63
|
+
* Every kind's fields.
|
|
64
|
+
*
|
|
65
|
+
* Spread from {@link ADDRESS_FIELDS} rather than written five times, with the
|
|
66
|
+
* per-kind annotation doing the checking: the three shared entries plus
|
|
67
|
+
* whatever that kind adds has to be exactly the fields the schema gives it.
|
|
68
|
+
*/
|
|
69
|
+
export const SIGNAL_FIELDS = {
|
|
70
|
+
viewed: { ...ADDRESS_FIELDS, at: AT },
|
|
71
|
+
dwelled: {
|
|
72
|
+
...ADDRESS_FIELDS,
|
|
73
|
+
ms: {
|
|
74
|
+
subject: "observation",
|
|
75
|
+
says: "how long it was on your screen since the last delivery, in milliseconds",
|
|
76
|
+
},
|
|
77
|
+
},
|
|
78
|
+
activated: { ...ADDRESS_FIELDS, at: AT, within: WITHIN },
|
|
79
|
+
disclosed: {
|
|
80
|
+
...ADDRESS_FIELDS,
|
|
81
|
+
open: { subject: "observation", says: "whether it was opened or closed" },
|
|
82
|
+
at: AT,
|
|
83
|
+
within: WITHIN,
|
|
84
|
+
},
|
|
85
|
+
completed: { ...ADDRESS_FIELDS, at: AT, within: WITHIN },
|
|
86
|
+
};
|
|
87
|
+
/** What travels with a delivery, whatever observations are in it. */
|
|
88
|
+
export const DELIVERY_FIELDS = {
|
|
89
|
+
treeId: { subject: "page", says: "which page it was" },
|
|
90
|
+
revision: {
|
|
91
|
+
subject: "page",
|
|
92
|
+
says: "which revision of that page you were served, so that an observation keeps its meaning after the page changes",
|
|
93
|
+
},
|
|
94
|
+
sentAt: { subject: "delivery", says: "when the delivery left your browser" },
|
|
95
|
+
audience: {
|
|
96
|
+
subject: "page",
|
|
97
|
+
says: "which form of the page you were served, by the name the deployment gave that form — a name for a group," +
|
|
98
|
+
" never a name for you, and nothing about why you matched it",
|
|
99
|
+
},
|
|
100
|
+
view: {
|
|
101
|
+
subject: "page-view",
|
|
102
|
+
says: "a random key that ties this delivery to the others from the same visit to this page, so that steps can be" +
|
|
103
|
+
" counted in order; it is tied to nothing else, it is never stored beside the counters, and it is gone when" +
|
|
104
|
+
" the delivery is",
|
|
105
|
+
},
|
|
106
|
+
first: {
|
|
107
|
+
subject: "page-view",
|
|
108
|
+
says: "whether this was the opening delivery of the visit, which is how arrivals are counted once rather than once per delivery",
|
|
109
|
+
},
|
|
110
|
+
signals: { subject: "delivery", says: "the observations themselves" },
|
|
111
|
+
};
|
|
112
|
+
/** The closed set, for a surface listing what is refused. */
|
|
113
|
+
export const REFUSALS = everyMemberOf()([
|
|
114
|
+
"no-identifier",
|
|
115
|
+
"no-fingerprint",
|
|
116
|
+
"no-content",
|
|
117
|
+
"no-pointer-path",
|
|
118
|
+
"no-stitching",
|
|
119
|
+
"no-address",
|
|
120
|
+
]);
|
|
121
|
+
/** One line per refusal, addressed to the reader. */
|
|
122
|
+
export const describeRefusal = (refusal) => {
|
|
123
|
+
switch (refusal) {
|
|
124
|
+
case "no-identifier":
|
|
125
|
+
return "nothing that identifies you: no account, no visitor id, no device id, and nothing derived from your browser to stand in for one";
|
|
126
|
+
case "no-fingerprint":
|
|
127
|
+
return "nothing about your device, your browser or your settings, and so nothing that could be combined into a signature for you";
|
|
128
|
+
case "no-content":
|
|
129
|
+
return "nothing the page showed you and nothing you typed into it: no text, no link target, no form value";
|
|
130
|
+
case "no-pointer-path":
|
|
131
|
+
return "no cursor positions, no scroll trace, and no recording of your session";
|
|
132
|
+
case "no-stitching":
|
|
133
|
+
return "nothing that joins this visit to another one, here or on any other page, so there is no history of you to hold";
|
|
134
|
+
case "no-address":
|
|
135
|
+
return "nothing derived from the address your request arrived from outlives the request, and the address itself is never stored";
|
|
136
|
+
}
|
|
137
|
+
};
|
|
138
|
+
/** One or two sentences about where readers are counted from, addressed to the reader. */
|
|
139
|
+
export const describeRegionNotice = (notice) => notice.floor === null
|
|
140
|
+
? "nothing about where you are is read, not even your country"
|
|
141
|
+
: `the country your request arrives from is counted, and nothing finer than the country; a country is published only once at least ${notice.floor} visits are counted in it, and the address it was read from is never stored`;
|
|
142
|
+
/** What each kind observes, in the reader's own terms rather than the browser's. */
|
|
143
|
+
const OBSERVES = {
|
|
144
|
+
viewed: "that a part of the page came onto your screen",
|
|
145
|
+
dwelled: "how long a part of the page stayed on your screen",
|
|
146
|
+
activated: "that you used a link, a button or a field, and which part of the page it was in",
|
|
147
|
+
disclosed: "that you opened or closed a part of the page",
|
|
148
|
+
completed: "that a form you filled in was submitted — that it left your browser, and never what was in it",
|
|
149
|
+
};
|
|
150
|
+
/**
|
|
151
|
+
* A length of time as a notice says it.
|
|
152
|
+
*
|
|
153
|
+
* Minutes above a minute and seconds below it, because the one number here a
|
|
154
|
+
* deployment could set low is the buffer and `collect.ts` floors it at a minute
|
|
155
|
+
* — so a notice reading *0 minutes* would be reporting a window the collector
|
|
156
|
+
* would refuse to run on.
|
|
157
|
+
*
|
|
158
|
+
* **Days above a day**, which the kept window asked for (0351): thirty days is
|
|
159
|
+
* the default a deployment keeps individual deliveries for, and *43200 minutes*
|
|
160
|
+
* is a number no reader of a privacy page can hold. The break is at a day
|
|
161
|
+
* rather than at an hour so that every figure a notice published before the
|
|
162
|
+
* kept window existed still reads exactly as it did — an hour is *60 minutes*
|
|
163
|
+
* here, as it has been, and the one new figure is the one that needed a bigger
|
|
164
|
+
* unit.
|
|
165
|
+
*/
|
|
166
|
+
const inWords = (ms) => {
|
|
167
|
+
if (ms < 60_000) {
|
|
168
|
+
const seconds = Math.round(ms / 1000);
|
|
169
|
+
return seconds === 1 ? "a second" : `${seconds} seconds`;
|
|
170
|
+
}
|
|
171
|
+
if (ms < 24 * 60 * 60_000) {
|
|
172
|
+
const minutes = Math.round(ms / 60_000);
|
|
173
|
+
return minutes === 1 ? "a minute" : `${minutes} minutes`;
|
|
174
|
+
}
|
|
175
|
+
const days = Math.round(ms / (24 * 60 * 60_000));
|
|
176
|
+
return days === 1 ? "a day" : `${days} days`;
|
|
177
|
+
};
|
|
178
|
+
/**
|
|
179
|
+
* How long a delivery lives, addressed to the reader.
|
|
180
|
+
*
|
|
181
|
+
* It takes the retention whole, because the two ages are the halves the
|
|
182
|
+
* framework knows and the sweep is the half it cannot promise, and a notice
|
|
183
|
+
* that published an age without the sweep said *a delivery is kept until it is
|
|
184
|
+
* 60 minutes old* to a reader who had no way of hearing *…or for ever, if
|
|
185
|
+
* nobody runs the sweep*. Where a schedule was stated the sentence ends on a
|
|
186
|
+
* ceiling a reader can hold the deployment to; where none was, it says that in
|
|
187
|
+
* as many words rather than leaving the ages to be read as a promise.
|
|
188
|
+
*
|
|
189
|
+
* **Two ages since 5 November, and saying one of them would be the lie** (0349,
|
|
190
|
+
* 0351). A delivery is counted at the first age and deleted at the second, and
|
|
191
|
+
* the sentence is explicit about what the gap is for: so that the deployment
|
|
192
|
+
* can look at the deliveries behind its totals. A reader told only *counted
|
|
193
|
+
* into totals* would reasonably assume the delivery was gone.
|
|
194
|
+
*/
|
|
195
|
+
export const describeBuffer = (retention) => {
|
|
196
|
+
const counts = `a delivery is counted into this deployment's totals once it is ${inWords(retention.bufferMs)} old`;
|
|
197
|
+
const kept = `it is then kept for ${inWords(retention.keptMs)} from when it arrived, so that this deployment can look at the deliveries its totals were made from, and its own sweep is what deletes it`;
|
|
198
|
+
const totals = "the totals it leaves behind have nobody in them, and they are kept";
|
|
199
|
+
return retention.sweep.state === "stated"
|
|
200
|
+
? `${counts}; ${kept}; that sweep runs at least every ${inWords(retention.sweep.everyMs)}, so a delivery is gone within ${inWords(retention.sweep.goneWithinMs)} of arriving — the key tying one visit together exists until then and nowhere else; ${totals}`
|
|
201
|
+
: `${counts}; ${kept}; this deployment has not said how often that sweep runs, so nothing here promises when a kept delivery actually goes — the key tying one visit together exists until the sweep takes it and nowhere else; ${totals}`;
|
|
202
|
+
};
|
|
203
|
+
/**
|
|
204
|
+
* What a stated interval becomes on a notice.
|
|
205
|
+
*
|
|
206
|
+
* The ceiling is derived here and nowhere else, so that a surface cannot print
|
|
207
|
+
* a number that disagrees with the age beside it: it is the ripeness window
|
|
208
|
+
* plus one sweep, which is the same addition the stall check asks a deployment
|
|
209
|
+
* for in one number (0274).
|
|
210
|
+
*
|
|
211
|
+
* **Anything that is not a positive, finite interval is `unstated`** rather
|
|
212
|
+
* than an error or a nought. A nought would publish *gone within 60 minutes* on
|
|
213
|
+
* a deployment that sweeps when somebody remembers to, and this module's one
|
|
214
|
+
* standing rule is that it may overstate what is collected and may never
|
|
215
|
+
* overstate what is deleted.
|
|
216
|
+
*/
|
|
217
|
+
const sweepNoticeOf = (everyMs, bufferMs, keptMs) => everyMs === undefined || !Number.isFinite(everyMs) || everyMs <= 0
|
|
218
|
+
? { state: "unstated" }
|
|
219
|
+
: { state: "stated", everyMs, goneWithinMs: Math.max(bufferMs, keptMs) + everyMs };
|
|
220
|
+
/**
|
|
221
|
+
* What a page broadcast with these options reports, as a deployment may publish
|
|
222
|
+
* it.
|
|
223
|
+
*
|
|
224
|
+
* Pure, and allocation-per-call: no store, no clock, no DOM.
|
|
225
|
+
*
|
|
226
|
+
* The kinds come out in the vocabulary's order and each appears once, whatever
|
|
227
|
+
* order a configuration names them in and however often — a notice is read by
|
|
228
|
+
* somebody who did not write the configuration, and *dwelled, dwelled, viewed*
|
|
229
|
+
* is a leak of how the options were typed rather than a fact about the page.
|
|
230
|
+
*/
|
|
231
|
+
export const collectionNoticeOf = (request = {}) => {
|
|
232
|
+
const asked = request.page?.kinds;
|
|
233
|
+
const bufferMs = request.windowMs ?? DEFAULT_READER_SIGNAL_WINDOW_MS;
|
|
234
|
+
const keptMs = request.keptMs ?? DEFAULT_READER_EVENT_RETENTION_MS;
|
|
235
|
+
const collects = READER_SIGNAL_KINDS.filter((kind) => asked === undefined || asked.includes(kind)).map((kind) => ({
|
|
236
|
+
kind,
|
|
237
|
+
observes: OBSERVES[kind],
|
|
238
|
+
carries: fieldsOf(SIGNAL_FIELDS[kind]),
|
|
239
|
+
}));
|
|
240
|
+
return {
|
|
241
|
+
collects,
|
|
242
|
+
delivery: fieldsOf(DELIVERY_FIELDS),
|
|
243
|
+
refuses: REFUSALS,
|
|
244
|
+
region: { floor: request.region === undefined ? null : regionFloorOf(request.region.floor) },
|
|
245
|
+
bufferMs,
|
|
246
|
+
keptMs,
|
|
247
|
+
sweep: sweepNoticeOf(request.sweep?.everyMs, bufferMs, keptMs),
|
|
248
|
+
};
|
|
249
|
+
};
|
|
250
|
+
//# sourceMappingURL=notice.js.map
|