@jam-overture/loom 0.1.0 → 0.2.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/cli/templates.js +19 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +23 -1
- package/dist/data/resolve.d.ts +30 -3
- 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/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/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/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/reads.d.ts +11 -0
- package/dist/render/reads.js +12 -1
- package/dist/render/render.js +102 -7
- 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/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 +22 -0
- package/dist/runtime/index.d.ts +3 -0
- package/dist/runtime/index.js +3 -0
- package/dist/runtime/irreversibility.d.ts +64 -0
- package/dist/runtime/irreversibility.js +45 -0
- 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 +299 -0
- package/dist/runtime/policy-log.d.ts +406 -0
- package/dist/runtime/policy-log.js +285 -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 +65 -0
- package/dist/sdk/definition.js +22 -0
- package/dist/sdk/registry.d.ts +29 -2
- package/dist/sdk/registry.js +63 -1
- 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/applied-window.contract.d.ts +23 -0
- package/dist/signals/applied-window.contract.js +160 -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 +8 -2
- package/dist/signals/broadcast.js +58 -8
- package/dist/signals/change.d.ts +378 -0
- package/dist/signals/change.js +327 -0
- package/dist/signals/collect.d.ts +41 -0
- package/dist/signals/collect.js +88 -7
- 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/counters.d.ts +46 -0
- package/dist/signals/counters.js +102 -0
- package/dist/signals/deliver.d.ts +23 -4
- package/dist/signals/deliver.js +34 -6
- package/dist/signals/deployment-change.d.ts +371 -0
- package/dist/signals/deployment-change.js +268 -0
- package/dist/signals/deployment.d.ts +265 -0
- package/dist/signals/deployment.js +152 -0
- package/dist/signals/door.d.ts +92 -0
- package/dist/signals/door.js +53 -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/funnel-change.d.ts +548 -0
- package/dist/signals/funnel-change.js +361 -0
- package/dist/signals/funnel.d.ts +532 -0
- package/dist/signals/funnel.js +216 -0
- package/dist/signals/health.d.ts +497 -0
- package/dist/signals/health.js +361 -0
- package/dist/signals/index.d.ts +41 -0
- package/dist/signals/index.js +41 -0
- package/dist/signals/ingest.d.ts +56 -1
- package/dist/signals/ingest.js +91 -1
- package/dist/signals/journal.d.ts +11 -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-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 +636 -0
- package/dist/signals/library-reach-change.js +534 -0
- package/dist/signals/library-reach.d.ts +377 -0
- package/dist/signals/library-reach.js +227 -0
- package/dist/signals/library-word-reach-change.d.ts +567 -0
- package/dist/signals/library-word-reach-change.js +568 -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 +105 -14
- package/dist/signals/migrate.d.ts +17 -2
- package/dist/signals/migrate.js +122 -5
- package/dist/signals/notice.d.ts +334 -0
- package/dist/signals/notice.js +228 -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/parts.d.ts +344 -0
- package/dist/signals/parts.js +273 -0
- package/dist/signals/postgres.d.ts +16 -2
- package/dist/signals/postgres.js +390 -87
- 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 +141 -0
- package/dist/signals/retention.js +58 -0
- package/dist/signals/rollup.d.ts +67 -3
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +432 -1
- package/dist/signals/schema.js +157 -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 +848 -0
- package/dist/signals/silences.js +753 -0
- package/dist/signals/tally.d.ts +140 -11
- package/dist/signals/window-figures.d.ts +148 -0
- package/dist/signals/window-figures.js +42 -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/index.d.ts +19 -0
- package/dist/store/index.js +19 -0
- package/dist/store/memory.d.ts +2 -1
- package/dist/store/memory.js +48 -12
- package/dist/store/migrate.d.ts +80 -0
- package/dist/store/migrate.js +259 -7
- package/dist/store/postgres-applications.d.ts +4 -0
- package/dist/store/postgres-applications.js +197 -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 +16 -1
- package/dist/store/postgres.js +59 -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 +450 -2
- package/dist/store/schema.js +141 -5
- package/dist/store/store.d.ts +29 -6
- 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 +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +72 -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 +23 -0
- package/dist/telemetry/migrate.js +22 -1
- package/dist/telemetry/postgres.d.ts +10 -1
- package/dist/telemetry/postgres.js +172 -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/testing/application-contract.d.ts +14 -0
- package/dist/testing/application-contract.js +270 -0
- package/dist/testing/contracts.d.ts +12 -7
- package/dist/testing/contracts.js +12 -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 +140 -2
- 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/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/compare.d.ts +9 -0
- package/dist/tree/compare.js +18 -0
- 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 +98 -19
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { LoomDatabase } from "../store/database.js";
|
|
2
2
|
/**
|
|
3
|
-
* Creating the
|
|
3
|
+
* Creating the five reader-signal tables, with row level security switched on.
|
|
4
4
|
*
|
|
5
5
|
* The same shape as the store's and the journal's migrations, and here for the
|
|
6
6
|
* same reason: a DDL statement that lives in a document is a DDL statement a
|
|
@@ -12,9 +12,24 @@ import type { LoomDatabase } from "../store/database.js";
|
|
|
12
12
|
* is the only combination in Loom that could correlate anything across a
|
|
13
13
|
* tenancy boundary. It expires within hours; the policy does not depend on
|
|
14
14
|
* that.
|
|
15
|
+
*
|
|
16
|
+
* Every table is led by `application_id` (0269). The backfill is the column
|
|
17
|
+
* default rather than an `UPDATE`: these five never carried `project_id`, so
|
|
18
|
+
* there is no earlier spelling to correct the way `APPLICATION_ID_MIGRATION`
|
|
19
|
+
* corrects the store's — rows that predate the column belong to the deployment
|
|
20
|
+
* that wrote them, which is what `app_default` names.
|
|
21
|
+
*
|
|
22
|
+
* Every table then carries `audience_id`, the second migration 0273 owed and
|
|
23
|
+
* [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
|
|
24
|
+
* settles. Backfilled by its default for the stronger version of the same
|
|
25
|
+
* reason: a row written before the dimension existed was collected when there
|
|
26
|
+
* was one form of every page, so `aud_everyone` is what was true of it rather
|
|
27
|
+
* than a value somebody picked. The four counters take it into their keys; the
|
|
28
|
+
* buffer takes the column and keeps its key and its index, because nothing
|
|
29
|
+
* reads the buffer by audience.
|
|
15
30
|
*/
|
|
16
31
|
/**
|
|
17
|
-
* The
|
|
32
|
+
* The five tables, as statements a host can run.
|
|
18
33
|
*
|
|
19
34
|
* One statement per entry for the same reason the store's DDL is a list: a
|
|
20
35
|
* driver may refuse several commands in a single prepared statement, and
|
package/dist/signals/migrate.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { sql } from "drizzle-orm";
|
|
2
2
|
/**
|
|
3
|
-
* Creating the
|
|
3
|
+
* Creating the five reader-signal tables, with row level security switched on.
|
|
4
4
|
*
|
|
5
5
|
* The same shape as the store's and the journal's migrations, and here for the
|
|
6
6
|
* same reason: a DDL statement that lives in a document is a DDL statement a
|
|
@@ -12,9 +12,24 @@ import { sql } from "drizzle-orm";
|
|
|
12
12
|
* is the only combination in Loom that could correlate anything across a
|
|
13
13
|
* tenancy boundary. It expires within hours; the policy does not depend on
|
|
14
14
|
* that.
|
|
15
|
+
*
|
|
16
|
+
* Every table is led by `application_id` (0269). The backfill is the column
|
|
17
|
+
* default rather than an `UPDATE`: these five never carried `project_id`, so
|
|
18
|
+
* there is no earlier spelling to correct the way `APPLICATION_ID_MIGRATION`
|
|
19
|
+
* corrects the store's — rows that predate the column belong to the deployment
|
|
20
|
+
* that wrote them, which is what `app_default` names.
|
|
21
|
+
*
|
|
22
|
+
* Every table then carries `audience_id`, the second migration 0273 owed and
|
|
23
|
+
* [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
|
|
24
|
+
* settles. Backfilled by its default for the stronger version of the same
|
|
25
|
+
* reason: a row written before the dimension existed was collected when there
|
|
26
|
+
* was one form of every page, so `aud_everyone` is what was true of it rather
|
|
27
|
+
* than a value somebody picked. The four counters take it into their keys; the
|
|
28
|
+
* buffer takes the column and keeps its key and its index, because nothing
|
|
29
|
+
* reads the buffer by audience.
|
|
15
30
|
*/
|
|
16
31
|
/**
|
|
17
|
-
* The
|
|
32
|
+
* The five tables, as statements a host can run.
|
|
18
33
|
*
|
|
19
34
|
* One statement per entry for the same reason the store's DDL is a list: a
|
|
20
35
|
* driver may refuse several commands in a single prepared statement, and
|
|
@@ -23,6 +38,8 @@ import { sql } from "drizzle-orm";
|
|
|
23
38
|
*/
|
|
24
39
|
export const READER_SIGNALS_DDL = [
|
|
25
40
|
`CREATE TABLE IF NOT EXISTS loom_reader_signals (
|
|
41
|
+
application_id text NOT NULL DEFAULT 'app_default',
|
|
42
|
+
audience_id text NOT NULL DEFAULT 'aud_everyone',
|
|
26
43
|
seq bigserial PRIMARY KEY,
|
|
27
44
|
tree_id text NOT NULL,
|
|
28
45
|
revision integer NOT NULL,
|
|
@@ -31,9 +48,41 @@ export const READER_SIGNALS_DDL = [
|
|
|
31
48
|
signals jsonb NOT NULL,
|
|
32
49
|
received_at timestamptz NOT NULL DEFAULT now()
|
|
33
50
|
)`,
|
|
34
|
-
|
|
51
|
+
/**
|
|
52
|
+
* **The application, for a database that predates it (0269).** The same
|
|
53
|
+
* shape the store's tables take: the column is additive and defaulted, and
|
|
54
|
+
* then the index is rebuilt to lead with it.
|
|
55
|
+
*
|
|
56
|
+
* The buffer's key does not widen, unlike the four counters below. It is
|
|
57
|
+
* `seq`, a `bigserial`, which is already unique across every application the
|
|
58
|
+
* database holds — so leading the key with the application would be a wider
|
|
59
|
+
* key for no constraint that was not already enforced. The index is the part
|
|
60
|
+
* that matters here, because the index is what the reads use.
|
|
61
|
+
*
|
|
62
|
+
* Dropped by name rather than created `IF NOT EXISTS`, for the reason the
|
|
63
|
+
* store's note gives: the name does not change, so an existing index on the
|
|
64
|
+
* old columns would be left exactly as it was and every read would go on
|
|
65
|
+
* scanning across applications while appearing to be indexed.
|
|
66
|
+
*/
|
|
67
|
+
`ALTER TABLE loom_reader_signals ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
|
|
68
|
+
/**
|
|
69
|
+
* **The audience, for a database that predates it (0284).** Additive and
|
|
70
|
+
* defaulted, and here the index is *not* rebuilt around it — the one place
|
|
71
|
+
* this dimension departs from the shape the application took.
|
|
72
|
+
*
|
|
73
|
+
* Every read of the buffer filters the application, optionally the tree, and
|
|
74
|
+
* the sequence; none of them filters the audience, because a rollup folds a
|
|
75
|
+
* whole window and groups by the column afterwards. Leading the index with it
|
|
76
|
+
* would push `tree_id` and `seq` out of the prefix and widen every scan that
|
|
77
|
+
* exists to serve a filter nothing expresses.
|
|
78
|
+
*/
|
|
79
|
+
`ALTER TABLE loom_reader_signals ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
|
|
80
|
+
`DROP INDEX IF EXISTS loom_reader_signals_tree_seq_idx`,
|
|
81
|
+
`CREATE INDEX IF NOT EXISTS loom_reader_signals_tree_seq_idx ON loom_reader_signals (application_id, tree_id, seq)`,
|
|
35
82
|
`ALTER TABLE loom_reader_signals ENABLE ROW LEVEL SECURITY`,
|
|
36
83
|
`CREATE TABLE IF NOT EXISTS loom_reader_tallies (
|
|
84
|
+
application_id text NOT NULL DEFAULT 'app_default',
|
|
85
|
+
audience_id text NOT NULL DEFAULT 'aud_everyone',
|
|
37
86
|
tree_id text NOT NULL,
|
|
38
87
|
revision integer NOT NULL,
|
|
39
88
|
node_id text NOT NULL,
|
|
@@ -45,8 +94,9 @@ export const READER_SIGNALS_DDL = [
|
|
|
45
94
|
activations bigint NOT NULL,
|
|
46
95
|
opens bigint NOT NULL,
|
|
47
96
|
closes bigint NOT NULL,
|
|
97
|
+
completions bigint NOT NULL DEFAULT 0,
|
|
48
98
|
updated_at timestamptz NOT NULL,
|
|
49
|
-
PRIMARY KEY (tree_id, revision, node_id)
|
|
99
|
+
PRIMARY KEY (application_id, audience_id, tree_id, revision, node_id)
|
|
50
100
|
)`,
|
|
51
101
|
/**
|
|
52
102
|
* For a deployment whose tallies table predates the counter regions are
|
|
@@ -54,8 +104,22 @@ export const READER_SIGNALS_DDL = [
|
|
|
54
104
|
* measured doing anything in here*, which is what was true of them.
|
|
55
105
|
*/
|
|
56
106
|
`ALTER TABLE loom_reader_tallies ADD COLUMN IF NOT EXISTS engaged bigint NOT NULL DEFAULT 0`,
|
|
107
|
+
/**
|
|
108
|
+
* For a deployment whose tallies table predates the fifth kind. Additive and
|
|
109
|
+
* defaulted, so existing rows read as *nothing was submitted here*, which is
|
|
110
|
+
* what nobody was counting.
|
|
111
|
+
*/
|
|
112
|
+
`ALTER TABLE loom_reader_tallies ADD COLUMN IF NOT EXISTS completions bigint NOT NULL DEFAULT 0`,
|
|
113
|
+
/** The application, for a database that predates it — see the buffer's note above. */
|
|
114
|
+
`ALTER TABLE loom_reader_tallies ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
|
|
115
|
+
/** The audience, for a database that predates it — see the buffer's note above. */
|
|
116
|
+
`ALTER TABLE loom_reader_tallies ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
|
|
117
|
+
`ALTER TABLE loom_reader_tallies DROP CONSTRAINT IF EXISTS loom_reader_tallies_pkey`,
|
|
118
|
+
`ALTER TABLE loom_reader_tallies ADD PRIMARY KEY (application_id, audience_id, tree_id, revision, node_id)`,
|
|
57
119
|
`ALTER TABLE loom_reader_tallies ENABLE ROW LEVEL SECURITY`,
|
|
58
120
|
`CREATE TABLE IF NOT EXISTS loom_reader_funnels (
|
|
121
|
+
application_id text NOT NULL DEFAULT 'app_default',
|
|
122
|
+
audience_id text NOT NULL DEFAULT 'aud_everyone',
|
|
59
123
|
tree_id text NOT NULL,
|
|
60
124
|
revision integer NOT NULL,
|
|
61
125
|
from_node_id text NOT NULL,
|
|
@@ -65,9 +129,62 @@ export const READER_SIGNALS_DDL = [
|
|
|
65
129
|
reached bigint NOT NULL,
|
|
66
130
|
converted bigint NOT NULL,
|
|
67
131
|
updated_at timestamptz NOT NULL,
|
|
68
|
-
PRIMARY KEY (tree_id, revision, from_node_id, from_kind, to_node_id, to_kind)
|
|
132
|
+
PRIMARY KEY (application_id, audience_id, tree_id, revision, from_node_id, from_kind, to_node_id, to_kind)
|
|
69
133
|
)`,
|
|
134
|
+
/** The application, for a database that predates it — see the buffer's note above. */
|
|
135
|
+
`ALTER TABLE loom_reader_funnels ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
|
|
136
|
+
/** The audience, for a database that predates it — see the buffer's note above. */
|
|
137
|
+
`ALTER TABLE loom_reader_funnels ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
|
|
138
|
+
`ALTER TABLE loom_reader_funnels DROP CONSTRAINT IF EXISTS loom_reader_funnels_pkey`,
|
|
139
|
+
`ALTER TABLE loom_reader_funnels ADD PRIMARY KEY (application_id, audience_id, tree_id, revision, from_node_id, from_kind, to_node_id, to_kind)`,
|
|
70
140
|
`ALTER TABLE loom_reader_funnels ENABLE ROW LEVEL SECURITY`,
|
|
141
|
+
`CREATE TABLE IF NOT EXISTS loom_reader_regions (
|
|
142
|
+
application_id text NOT NULL DEFAULT 'app_default',
|
|
143
|
+
audience_id text NOT NULL DEFAULT 'aud_everyone',
|
|
144
|
+
tree_id text NOT NULL,
|
|
145
|
+
revision integer NOT NULL,
|
|
146
|
+
region text NOT NULL,
|
|
147
|
+
views bigint NOT NULL,
|
|
148
|
+
updated_at timestamptz NOT NULL,
|
|
149
|
+
PRIMARY KEY (application_id, audience_id, tree_id, revision, region)
|
|
150
|
+
)`,
|
|
151
|
+
/** The application, for a database that predates it — see the buffer's note above. */
|
|
152
|
+
`ALTER TABLE loom_reader_regions ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
|
|
153
|
+
/** The audience, for a database that predates it — see the buffer's note above. */
|
|
154
|
+
`ALTER TABLE loom_reader_regions ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
|
|
155
|
+
`ALTER TABLE loom_reader_regions DROP CONSTRAINT IF EXISTS loom_reader_regions_pkey`,
|
|
156
|
+
`ALTER TABLE loom_reader_regions ADD PRIMARY KEY (application_id, audience_id, tree_id, revision, region)`,
|
|
157
|
+
`ALTER TABLE loom_reader_regions ENABLE ROW LEVEL SECURITY`,
|
|
158
|
+
`CREATE TABLE IF NOT EXISTS loom_reader_page_views (
|
|
159
|
+
application_id text NOT NULL DEFAULT 'app_default',
|
|
160
|
+
audience_id text NOT NULL DEFAULT 'aud_everyone',
|
|
161
|
+
tree_id text NOT NULL,
|
|
162
|
+
revision integer NOT NULL,
|
|
163
|
+
opened bigint NOT NULL DEFAULT 0,
|
|
164
|
+
appearances bigint NOT NULL DEFAULT 0,
|
|
165
|
+
updated_at timestamptz NOT NULL,
|
|
166
|
+
folded_at timestamptz,
|
|
167
|
+
PRIMARY KEY (application_id, audience_id, tree_id, revision)
|
|
168
|
+
)`,
|
|
169
|
+
/**
|
|
170
|
+
* **When the fold last touched the row**, for a deployment whose page-view
|
|
171
|
+
* table predates the question.
|
|
172
|
+
*
|
|
173
|
+
* Additive, nullable and undefaulted, which is the only honest value: no
|
|
174
|
+
* backfill exists, because nothing wrote down when those rows were folded
|
|
175
|
+
* and `updated_at` cannot be read as it — it is written by the door as well.
|
|
176
|
+
* An existing row therefore reads *nothing attests a fold*, which is a state
|
|
177
|
+
* the reading publishes and raises no fault from, and the first fold after
|
|
178
|
+
* the migration fills it in.
|
|
179
|
+
*/
|
|
180
|
+
`ALTER TABLE loom_reader_page_views ADD COLUMN IF NOT EXISTS folded_at timestamptz`,
|
|
181
|
+
/** The application, for a database that predates it — see the buffer's note above. */
|
|
182
|
+
`ALTER TABLE loom_reader_page_views ADD COLUMN IF NOT EXISTS application_id text NOT NULL DEFAULT 'app_default'`,
|
|
183
|
+
/** The audience, for a database that predates it — see the buffer's note above. */
|
|
184
|
+
`ALTER TABLE loom_reader_page_views ADD COLUMN IF NOT EXISTS audience_id text NOT NULL DEFAULT 'aud_everyone'`,
|
|
185
|
+
`ALTER TABLE loom_reader_page_views DROP CONSTRAINT IF EXISTS loom_reader_page_views_pkey`,
|
|
186
|
+
`ALTER TABLE loom_reader_page_views ADD PRIMARY KEY (application_id, audience_id, tree_id, revision)`,
|
|
187
|
+
`ALTER TABLE loom_reader_page_views ENABLE ROW LEVEL SECURITY`,
|
|
71
188
|
];
|
|
72
189
|
/** Idempotent, so running it against a populated database is a no-op. */
|
|
73
190
|
export const ensureReaderSignalsSchema = async (db) => {
|
|
@@ -0,0 +1,334 @@
|
|
|
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: its ripeness window plus one sweep
|
|
199
|
+
* interval.
|
|
200
|
+
*
|
|
201
|
+
* The two add because a delivery is not counted until it ripens and then
|
|
202
|
+
* not until the next sweep runs, which is the arithmetic
|
|
203
|
+
* `CollectionSchedule.foldsWithinMs` spells out for the operator's half
|
|
204
|
+
* of this question (0274) — so **this is the number to hand the stall
|
|
205
|
+
* check**, and a deployment states the interval once rather than keeping
|
|
206
|
+
* a reader's ceiling and an operator's threshold in step by hand.
|
|
207
|
+
*/
|
|
208
|
+
readonly goneWithinMs: number;
|
|
209
|
+
}
|
|
210
|
+
/** Nothing was stated, so nothing here says when a ripe delivery actually goes. */
|
|
211
|
+
| {
|
|
212
|
+
readonly state: "unstated";
|
|
213
|
+
};
|
|
214
|
+
/** What a published page reports, and what it refuses to. */
|
|
215
|
+
export type CollectionNotice = {
|
|
216
|
+
/** The kinds this configuration broadcasts, in the vocabulary's order. */
|
|
217
|
+
readonly collects: readonly CollectedKind[];
|
|
218
|
+
/** What travels with every delivery. */
|
|
219
|
+
readonly delivery: readonly CollectedField[];
|
|
220
|
+
/** What is never collected, whatever else is configured. */
|
|
221
|
+
readonly refuses: readonly Refusal[];
|
|
222
|
+
/** Where readers are counted from, or that they are not. */
|
|
223
|
+
readonly region: RegionNotice;
|
|
224
|
+
/**
|
|
225
|
+
* How long a delivery itself lives before it is counted and dropped, in
|
|
226
|
+
* milliseconds.
|
|
227
|
+
*
|
|
228
|
+
* The deployment's own number (`collect.ts`), and the honest bound on the
|
|
229
|
+
* life of the page-view key, since the key exists in the buffer and nowhere
|
|
230
|
+
* else. **The framework cannot promise the moment it is swept**, because a
|
|
231
|
+
* host schedules the sweep: this is the age at which a delivery becomes ripe,
|
|
232
|
+
* not a guarantee about when the next run happens. What the deployment itself
|
|
233
|
+
* promises about that is {@link CollectionNotice.sweep}, and
|
|
234
|
+
* {@link describeBuffer} says the two together.
|
|
235
|
+
*/
|
|
236
|
+
readonly bufferMs: number;
|
|
237
|
+
/**
|
|
238
|
+
* How often this deployment sweeps a ripe delivery away, where it has stated
|
|
239
|
+
* it.
|
|
240
|
+
*
|
|
241
|
+
* The half of retention that is not the framework's to promise, and the half
|
|
242
|
+
* a reader of `bufferMs` alone would assume. {@link describeBuffer} takes the
|
|
243
|
+
* two together for that reason: an age with no sweep beside it is a sentence
|
|
244
|
+
* that reads like a deletion and is not one.
|
|
245
|
+
*/
|
|
246
|
+
readonly sweep: SweepNotice;
|
|
247
|
+
};
|
|
248
|
+
/** One kind of observation, with the fields it carries. */
|
|
249
|
+
export type CollectedKind = {
|
|
250
|
+
readonly kind: ReaderSignalKind;
|
|
251
|
+
/** What the page observed, addressed to the reader. */
|
|
252
|
+
readonly observes: string;
|
|
253
|
+
/** Every field that kind carries, including the ones it sometimes omits. */
|
|
254
|
+
readonly carries: readonly CollectedField[];
|
|
255
|
+
};
|
|
256
|
+
/**
|
|
257
|
+
* Both halves of how long a delivery lives: the age it ripens at, and how often
|
|
258
|
+
* the deployment takes the ripe ones away.
|
|
259
|
+
*
|
|
260
|
+
* A `Pick` of the notice rather than two arguments, so that the sentence cannot
|
|
261
|
+
* be built from one of them. The age alone reads as a deletion and is not one.
|
|
262
|
+
*/
|
|
263
|
+
export type DeliveryRetention = Pick<CollectionNotice, "bufferMs" | "sweep">;
|
|
264
|
+
/**
|
|
265
|
+
* How long a delivery lives, addressed to the reader.
|
|
266
|
+
*
|
|
267
|
+
* It takes the retention whole, because the age is the half the framework knows
|
|
268
|
+
* and the sweep is the half it cannot promise, and a notice that published the
|
|
269
|
+
* first without the second said *a delivery is kept until it is 60 minutes old*
|
|
270
|
+
* to a reader who had no way of hearing *…or for ever, if nobody runs the
|
|
271
|
+
* sweep*. Where a schedule was stated the sentence ends on a ceiling a reader
|
|
272
|
+
* can hold the deployment to; where none was, it says that in as many words
|
|
273
|
+
* rather than leaving the age to be read as a promise.
|
|
274
|
+
*/
|
|
275
|
+
export declare const describeBuffer: (retention: DeliveryRetention) => string;
|
|
276
|
+
/** The configuration a notice is of. */
|
|
277
|
+
export type NoticeRequest = {
|
|
278
|
+
/**
|
|
279
|
+
* The options the page is broadcast with — the same object, so that a notice
|
|
280
|
+
* and the page it is about cannot disagree about which kinds are reported.
|
|
281
|
+
*
|
|
282
|
+
* Only `kinds` is read. `types` and `within` narrow collection below what the
|
|
283
|
+
* notice says, which is the ceiling rule above.
|
|
284
|
+
*/
|
|
285
|
+
readonly page?: Pick<ReaderSignalOptions, "kinds">;
|
|
286
|
+
/**
|
|
287
|
+
* The window the deployment collects on, from its own `CollectionRequest`
|
|
288
|
+
* (`collect.ts`). The default when absent.
|
|
289
|
+
*
|
|
290
|
+
* Reported as given rather than clamped: `collect.ts` is what refuses a
|
|
291
|
+
* window below its minimum, and a notice that silently reported a different
|
|
292
|
+
* number from the one a deployment configured would be a second rule about
|
|
293
|
+
* one setting.
|
|
294
|
+
*/
|
|
295
|
+
readonly windowMs?: number;
|
|
296
|
+
/**
|
|
297
|
+
* The region counting this deployment's intake does, where it does any.
|
|
298
|
+
*
|
|
299
|
+
* Absent is *no country is read*, which is the default: reading one is
|
|
300
|
+
* something an intake is configured to do (§7). A floor below the published
|
|
301
|
+
* minimum is raised to it, by the same helper the region map itself uses.
|
|
302
|
+
*/
|
|
303
|
+
readonly region?: {
|
|
304
|
+
readonly floor?: number;
|
|
305
|
+
};
|
|
306
|
+
/**
|
|
307
|
+
* How often this deployment's sweep runs, where it has stated it.
|
|
308
|
+
*
|
|
309
|
+
* Absent is *nothing is stated*, which is the honest default: nothing in this
|
|
310
|
+
* subsystem schedules a sweep, so a notice that assumed one would publish a
|
|
311
|
+
* ceiling no deployment promised. A value that is not a positive, finite
|
|
312
|
+
* number of milliseconds is read the same way — the notice may always
|
|
313
|
+
* promise a reader less than the deployment knows and may never promise more,
|
|
314
|
+
* and the operator-facing half, where a value that could not be read is said
|
|
315
|
+
* out loud, is a deployment's own settings (0317).
|
|
316
|
+
*/
|
|
317
|
+
readonly sweep?: {
|
|
318
|
+
readonly everyMs: number;
|
|
319
|
+
};
|
|
320
|
+
};
|
|
321
|
+
/**
|
|
322
|
+
* What a page broadcast with these options reports, as a deployment may publish
|
|
323
|
+
* it.
|
|
324
|
+
*
|
|
325
|
+
* Pure, and allocation-per-call: no store, no clock, no DOM.
|
|
326
|
+
*
|
|
327
|
+
* The kinds come out in the vocabulary's order and each appears once, whatever
|
|
328
|
+
* order a configuration names them in and however often — a notice is read by
|
|
329
|
+
* somebody who did not write the configuration, and *dwelled, dwelled, viewed*
|
|
330
|
+
* is a leak of how the options were typed rather than a fact about the page.
|
|
331
|
+
*/
|
|
332
|
+
export declare const collectionNoticeOf: (request?: NoticeRequest) => CollectionNotice;
|
|
333
|
+
export {};
|
|
334
|
+
//# sourceMappingURL=notice.d.ts.map
|