@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,263 @@
|
|
|
1
|
+
import { outlineTree } from "../tree/outline.js";
|
|
2
|
+
import { actedCountOf, } from "./acted.js";
|
|
3
|
+
import { audiencesIn } from "./audiences.js";
|
|
4
|
+
import { ownCopy, rolesByType } from "./join.js";
|
|
5
|
+
/**
|
|
6
|
+
* **What readers did inside each part of a page, over a range.**
|
|
7
|
+
*
|
|
8
|
+
* [`parts.ts`](parts.ts) joins a window's tallies to the tree they were filed
|
|
9
|
+
* against, which answers *which parts of this page are read and which are
|
|
10
|
+
* scrolled past* — for a window, since counting began, with no clock in it.
|
|
11
|
+
* [`acted.ts`](acted.ts) put a clock on the three kinds a reader aimed at
|
|
12
|
+
* something to cause (0362), which answers *what readers did to this part, by
|
|
13
|
+
* the hour* — for one part, or for a page with the part dimension collapsed.
|
|
14
|
+
*
|
|
15
|
+
* Neither answers the question a page's own shape asks: **a reader pressed
|
|
16
|
+
* something; what was it inside?**
|
|
17
|
+
*
|
|
18
|
+
* ## The payload already refused to answer this, and was right to
|
|
19
|
+
* [0167](../../decisions/0167-a-delegated-signal-names-the-regions-it-happened-inside.md)
|
|
20
|
+
* put `within` on the three delegated kinds — the addressed ancestors a press
|
|
21
|
+
* happened inside — and refused it on `viewed` and `dwelled`, where the payload
|
|
22
|
+
* would have been multiplied by the depth of the page to buy what a server can
|
|
23
|
+
* derive. The fold spends that `within` on one counter: `engaged`, a *distinct
|
|
24
|
+
* count of page views* on each ancestor (`rollup.ts`). Distinct counts do not
|
|
25
|
+
* add and the tally keeps no time, so `engaged` cannot answer *how many presses
|
|
26
|
+
* landed in the pricing band last Tuesday* — and the hourly counter cannot
|
|
27
|
+
* either, because it writes a row for the node a signal **named** and for no
|
|
28
|
+
* ancestor of it.
|
|
29
|
+
*
|
|
30
|
+
* **So the ancestry is derived here, from the tree, and not read off the wire at
|
|
31
|
+
* all.** Every row names a tree, a revision and a node; the tree the counters
|
|
32
|
+
* name says what that node sits inside; a sum over a subtree is the answer. No
|
|
33
|
+
* byte is added to any payload, no browser changes, nothing new is stored, and
|
|
34
|
+
* the reading works on batches whose `within` was missing altogether — which is
|
|
35
|
+
* every batch synthesised on a server or replayed from a fixture (`rollup.ts`
|
|
36
|
+
* names that case).
|
|
37
|
+
*
|
|
38
|
+
* ## Why the sum is exact, which is the whole reason this is publishable
|
|
39
|
+
*
|
|
40
|
+
* Every signal of these three kinds wrote **one** hourly row, on **one** node:
|
|
41
|
+
* the one it named. So a subtree's total counts each action exactly once, at
|
|
42
|
+
* whatever depth it happened, and a part's own count plus the totals of the
|
|
43
|
+
* parts immediately inside it is its own total — an invariant, asserted rather
|
|
44
|
+
* than hoped for. Adding occurrences is safe where adding `views`, `reached` or
|
|
45
|
+
* `engaged` is not (0147, 0284), and `ActedCounts` is separated from its key in
|
|
46
|
+
* `acted.ts` to say so in the types.
|
|
47
|
+
*
|
|
48
|
+
* It is the one counter in this subsystem that a nesting sum may be taken over.
|
|
49
|
+
* A reading that added `engaged` up a tree would count one reader's one press
|
|
50
|
+
* once per ancestor and the row would look right, which is why the shape here
|
|
51
|
+
* is four occurrence counters and nothing else.
|
|
52
|
+
*
|
|
53
|
+
* ## One revision, because the counts are laid on a tree
|
|
54
|
+
*
|
|
55
|
+
* `readReaderActed` reads every revision by default and adds them, which is
|
|
56
|
+
* what a goal wants (0350): a goal is a kind on a part and a part outlives a
|
|
57
|
+
* change to the page around it. This reading cannot do that. It lays counts on
|
|
58
|
+
* **a** tree, and a node's ancestry is a fact about one revision — the band a
|
|
59
|
+
* button sat in last week may not be the band it sits in now, and summing both
|
|
60
|
+
* revisions into one shape would attribute the earlier presses to the later
|
|
61
|
+
* page. Rows of another revision are dropped and counted, as `parts.ts` drops
|
|
62
|
+
* them, so a caller who passed the wrong pair can tell.
|
|
63
|
+
*
|
|
64
|
+
* Audiences, by contrast, **add**. Two forms of a page are two sets of rows over
|
|
65
|
+
* one tree at one revision (0263, 0284), and a press in one form plus a press in
|
|
66
|
+
* the other is two presses — a true count, because these are occurrences and not
|
|
67
|
+
* readers. `parts.ts` refuses a window of two audiences because its figures
|
|
68
|
+
* divide by distinct page views; nothing here divides by anything, so the rows
|
|
69
|
+
* are summed and the audiences they came from are published beside the answer
|
|
70
|
+
* (0297).
|
|
71
|
+
*
|
|
72
|
+
* ## Read time, not rollup time
|
|
73
|
+
*
|
|
74
|
+
* For `parts.ts`' reason, and one more. A declaration is a fact about the
|
|
75
|
+
* library rather than about a window of reading, so baking the join into stored
|
|
76
|
+
* rows makes today's silence permanent. Here the baking would be worse than
|
|
77
|
+
* permanent: it would be a second write per ancestor per hour, which is the
|
|
78
|
+
* payload explosion 0167 refused, moved from the wire into the database.
|
|
79
|
+
*
|
|
80
|
+
* Pure. Handed a tree, one read of the counter and the declarations; reaches no
|
|
81
|
+
* store, no clock and no DOM, and adds nothing to the broadcaster's import
|
|
82
|
+
* graph.
|
|
83
|
+
*/
|
|
84
|
+
const NO_COUNTS = Object.freeze({
|
|
85
|
+
activations: 0,
|
|
86
|
+
opens: 0,
|
|
87
|
+
closes: 0,
|
|
88
|
+
completions: 0,
|
|
89
|
+
});
|
|
90
|
+
const counting = () => ({ activations: 0, opens: 0, closes: 0, completions: 0 });
|
|
91
|
+
const addInto = (into, counts) => {
|
|
92
|
+
into.activations += counts.activations;
|
|
93
|
+
into.opens += counts.opens;
|
|
94
|
+
into.closes += counts.closes;
|
|
95
|
+
into.completions += counts.completions;
|
|
96
|
+
};
|
|
97
|
+
const frozen = (counts) => ({
|
|
98
|
+
activations: counts.activations,
|
|
99
|
+
opens: counts.opens,
|
|
100
|
+
closes: counts.closes,
|
|
101
|
+
completions: counts.completions,
|
|
102
|
+
});
|
|
103
|
+
/**
|
|
104
|
+
* Join a range of the hourly counter to the tree and registry it was filed
|
|
105
|
+
* against, and read it as the page's own shape.
|
|
106
|
+
*
|
|
107
|
+
* **One read in, one reading out, and that is a guard rather than an
|
|
108
|
+
* ergonomic.** `parts.ts` can refuse a tally handed in twice because a tally is
|
|
109
|
+
* one row per part; an hour's counter legitimately has many rows per part, so a
|
|
110
|
+
* duplicate here is invisible and would inflate every ancestor of it. Taking a
|
|
111
|
+
* single {@link StoredActed} is what makes *a caller passed the same rows
|
|
112
|
+
* twice* unspellable instead of undetectable (0158).
|
|
113
|
+
*
|
|
114
|
+
* Linear in the parts and in the rows: the rows are bucketed once, the parts are
|
|
115
|
+
* walked once to find each one's nearest addressed ancestor, and the subtree
|
|
116
|
+
* totals are accumulated in one pass back up the same list. The reading the
|
|
117
|
+
* ledger's bound exists for (rule 4) is not allowed to walk a part's ancestors
|
|
118
|
+
* per part.
|
|
119
|
+
*/
|
|
120
|
+
export const insideReadingOf = (tree, stored, declarations, range) => {
|
|
121
|
+
const own = new Map();
|
|
122
|
+
const here = [];
|
|
123
|
+
let foreign = 0;
|
|
124
|
+
let outside = 0;
|
|
125
|
+
for (const row of stored.hours) {
|
|
126
|
+
if (row.treeId !== tree.treeId || row.revision !== tree.revision) {
|
|
127
|
+
foreign += 1;
|
|
128
|
+
continue;
|
|
129
|
+
}
|
|
130
|
+
if (row.hour < range.from || row.hour >= range.to) {
|
|
131
|
+
outside += 1;
|
|
132
|
+
continue;
|
|
133
|
+
}
|
|
134
|
+
here.push(row);
|
|
135
|
+
const into = own.get(row.nodeId) ?? counting();
|
|
136
|
+
addInto(into, row);
|
|
137
|
+
own.set(row.nodeId, into);
|
|
138
|
+
}
|
|
139
|
+
const roles = rolesByType(declarations);
|
|
140
|
+
/**
|
|
141
|
+
* The nearest addressed ancestor of each part, found by carrying the stack of
|
|
142
|
+
* open elements down the pre-order walk. A part's own ancestors are therefore
|
|
143
|
+
* never re-walked: the entry whose depth is not below the top of the stack has
|
|
144
|
+
* closed it, which is the only comparison this needs.
|
|
145
|
+
*/
|
|
146
|
+
const open = [];
|
|
147
|
+
const addressed = [];
|
|
148
|
+
for (const entry of outlineTree(tree.root)) {
|
|
149
|
+
while (open.length > 0 && (open.at(-1)?.depth ?? 0) >= entry.depth)
|
|
150
|
+
open.pop();
|
|
151
|
+
if (entry.node.kind !== "element")
|
|
152
|
+
continue;
|
|
153
|
+
addressed.push({
|
|
154
|
+
node: entry.node,
|
|
155
|
+
depth: entry.depth,
|
|
156
|
+
withinId: open.at(-1)?.nodeId ?? null,
|
|
157
|
+
});
|
|
158
|
+
open.push({ nodeId: entry.node.id, depth: entry.depth });
|
|
159
|
+
}
|
|
160
|
+
const inside = new Map(addressed.map(({ node }) => [node.id, counting()]));
|
|
161
|
+
const held = new Map(addressed.map(({ node }) => [node.id, 1]));
|
|
162
|
+
/**
|
|
163
|
+
* Reverse pre-order, so every part inside a part has already been totalled
|
|
164
|
+
* when the part itself is reached. One pass, whatever the shape of the page.
|
|
165
|
+
*/
|
|
166
|
+
for (const { node, withinId } of [...addressed].reverse()) {
|
|
167
|
+
const subtotal = inside.get(node.id);
|
|
168
|
+
if (subtotal === undefined)
|
|
169
|
+
continue;
|
|
170
|
+
addInto(subtotal, own.get(node.id) ?? NO_COUNTS);
|
|
171
|
+
if (withinId === null)
|
|
172
|
+
continue;
|
|
173
|
+
const above = inside.get(withinId);
|
|
174
|
+
if (above !== undefined)
|
|
175
|
+
addInto(above, subtotal);
|
|
176
|
+
const count = held.get(withinId);
|
|
177
|
+
if (count !== undefined)
|
|
178
|
+
held.set(withinId, count + (held.get(node.id) ?? 1));
|
|
179
|
+
}
|
|
180
|
+
const parts = addressed.map(({ node, depth, withinId }) => {
|
|
181
|
+
const subtotal = inside.get(node.id);
|
|
182
|
+
return {
|
|
183
|
+
nodeId: node.id,
|
|
184
|
+
type: node.type,
|
|
185
|
+
role: roles.get(node.type) ?? null,
|
|
186
|
+
depth,
|
|
187
|
+
withinId,
|
|
188
|
+
own: frozen(own.get(node.id) ?? counting()),
|
|
189
|
+
inside: subtotal === undefined ? NO_COUNTS : frozen(subtotal),
|
|
190
|
+
parts: held.get(node.id) ?? 1,
|
|
191
|
+
copy: ownCopy(node, declarations),
|
|
192
|
+
};
|
|
193
|
+
});
|
|
194
|
+
const total = counting();
|
|
195
|
+
for (const part of parts)
|
|
196
|
+
addInto(total, part.own);
|
|
197
|
+
const names = new Set(parts.map((part) => part.nodeId));
|
|
198
|
+
return {
|
|
199
|
+
treeId: tree.treeId,
|
|
200
|
+
revision: tree.revision,
|
|
201
|
+
range,
|
|
202
|
+
parts,
|
|
203
|
+
total: frozen(total),
|
|
204
|
+
audiences: audiencesIn(here),
|
|
205
|
+
counted: here.length,
|
|
206
|
+
foreign,
|
|
207
|
+
outside,
|
|
208
|
+
orphaned: [...own.keys()].filter((nodeId) => !names.has(nodeId)),
|
|
209
|
+
...(stored.begins === undefined ? {} : { begins: stored.begins }),
|
|
210
|
+
};
|
|
211
|
+
};
|
|
212
|
+
/**
|
|
213
|
+
* The parts readers acted on most in the range, most first.
|
|
214
|
+
*
|
|
215
|
+
* **By what readers did to the part itself**, never by what they did inside it:
|
|
216
|
+
* ordering by `inside` ranks every page by its outermost part, because an
|
|
217
|
+
* ancestor's total is never below its descendant's. The question this answers is
|
|
218
|
+
* *what did readers press*, and the answer to that is a button.
|
|
219
|
+
*
|
|
220
|
+
* One kind, for `actedSeriesOf`' reason — a list with presses and sends added
|
|
221
|
+
* together is a list of two different things — and parts nobody did anything to
|
|
222
|
+
* are absent rather than listed as noughts: the universe of parts that *could*
|
|
223
|
+
* have been pressed is not something a tree can say today, so a list padded with
|
|
224
|
+
* every heading on the page would read as a claim this reading cannot make.
|
|
225
|
+
* {@link InsideReading.parts} holds the whole page for a caller that wants it.
|
|
226
|
+
*
|
|
227
|
+
* Ties keep reading order, so a page with ten parts at one press each is drawn
|
|
228
|
+
* in the order it is written rather than in the order a sort happened to leave
|
|
229
|
+
* them.
|
|
230
|
+
*/
|
|
231
|
+
export const actedMostIn = (reading, kind, limit) => {
|
|
232
|
+
const ordered = reading.parts
|
|
233
|
+
.filter((part) => actedCountOf(part.own, kind) > 0)
|
|
234
|
+
.sort((left, right) => actedCountOf(right.own, kind) - actedCountOf(left.own, kind));
|
|
235
|
+
return limit === undefined ? ordered : ordered.slice(0, limit);
|
|
236
|
+
};
|
|
237
|
+
/**
|
|
238
|
+
* The share of everything readers did on the page, in one kind, that happened
|
|
239
|
+
* inside one part — between 0 and 1.
|
|
240
|
+
*
|
|
241
|
+
* *Sixty-two per cent of the presses on this page were in the pricing band* is
|
|
242
|
+
* the sentence, and it is exact rather than estimated: the numerator and the
|
|
243
|
+
* denominator are counts of the same occurrences over the same rows, and each
|
|
244
|
+
* occurrence is in both or in neither.
|
|
245
|
+
*
|
|
246
|
+
* `null` where readers did nothing of that kind on the page at all. A nought
|
|
247
|
+
* there would read as *this part gets none of them*, which is a claim about the
|
|
248
|
+
* part, and what is true is that there are none to share out.
|
|
249
|
+
*/
|
|
250
|
+
export const insideShareIn = (reading, part, kind) => {
|
|
251
|
+
const whole = actedCountOf(reading.total, kind);
|
|
252
|
+
return whole === 0 ? null : actedCountOf(part.inside, kind) / whole;
|
|
253
|
+
};
|
|
254
|
+
/**
|
|
255
|
+
* What readers did inside a part but not to the part itself.
|
|
256
|
+
*
|
|
257
|
+
* The figure that says whether a band is a thing readers use or a thing that
|
|
258
|
+
* holds things readers use — and the one a surface would otherwise get by
|
|
259
|
+
* subtracting two numbers it was handed, which is the subtraction that is wrong
|
|
260
|
+
* if either of them is the other kind's.
|
|
261
|
+
*/
|
|
262
|
+
export const beneathOf = (part, kind) => actedCountOf(part.inside, kind) - actedCountOf(part.own, kind);
|
|
263
|
+
//# sourceMappingURL=inside.js.map
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import type { PrimitiveType } from "../primitive-type.js";
|
|
2
|
+
import { type PrimitiveRole } from "../role.js";
|
|
3
|
+
import { type CopyDeclarations, type NodeCopy } from "../sdk/copy.js";
|
|
4
|
+
import type { ElementNode } from "../tree/node.js";
|
|
5
|
+
/**
|
|
6
|
+
* The two rules both joins of a window to a tree have to get the same answer
|
|
7
|
+
* to, spelled once.
|
|
8
|
+
*
|
|
9
|
+
* [`parts.ts`](parts.ts) joins the tallies and [`inside.ts`](inside.ts) joins
|
|
10
|
+
* the hourly counter, and both have to say what part a primitive plays (0114)
|
|
11
|
+
* and what words a part says itself (0122). Two spellings of either would be
|
|
12
|
+
* two chances for one of them to be wrong, and the second rule carries a
|
|
13
|
+
* sentence that a caller relies on: *the words of a page are partitioned across
|
|
14
|
+
* its parts exactly once*, which is what lets two rows be added together
|
|
15
|
+
* without a headline being read twice.
|
|
16
|
+
*
|
|
17
|
+
* **Not a published door.** These are the private middle of two readings rather
|
|
18
|
+
* than anything a host asks for, and `@jam-overture/loom/signals` is wide
|
|
19
|
+
* enough already — so this module is deliberately absent from the barrel, as
|
|
20
|
+
* `counters.ts` and `words.ts` are.
|
|
21
|
+
*/
|
|
22
|
+
/**
|
|
23
|
+
* Which types declared each role, as a registry answers it.
|
|
24
|
+
*
|
|
25
|
+
* The same shape as `CopyDeclarations` and for the same reason (0122): a
|
|
26
|
+
* registry built by the SDK satisfies it, and so does a two-line double in a
|
|
27
|
+
* test. The inverse — a type's role — is what both joins need and is not what
|
|
28
|
+
* 0114 exposes, because a role is a question asked of the vocabulary rather than
|
|
29
|
+
* of a component. The vocabulary is closed and exported, so the inversion is a
|
|
30
|
+
* walk of `PRIMITIVE_ROLES` rather than a method on the registry.
|
|
31
|
+
*
|
|
32
|
+
* Published, by way of `parts.ts` — a deployment hands one of these in.
|
|
33
|
+
*/
|
|
34
|
+
export type RoleDeclarations = {
|
|
35
|
+
readonly typesWithRole: (role: PrimitiveRole) => readonly PrimitiveType[];
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* A type's role, inverted from the vocabulary once per reading.
|
|
39
|
+
*
|
|
40
|
+
* Linear in the vocabulary rather than per part: the alternative is asking
|
|
41
|
+
* `typesWithRole` for every part, which is a registry call and a list scan per
|
|
42
|
+
* node on a page that may have thousands.
|
|
43
|
+
*/
|
|
44
|
+
export declare const rolesByType: (declarations: RoleDeclarations) => ReadonlyMap<PrimitiveType, PrimitiveRole>;
|
|
45
|
+
/**
|
|
46
|
+
* What a part says on its own, read with `copyIn` against a node stripped of
|
|
47
|
+
* everything that is a part in its own right.
|
|
48
|
+
*
|
|
49
|
+
* `copyIn` walks a subtree, which is right for its callers and wrong here — a
|
|
50
|
+
* root would carry every word on the page and so would every band on the way
|
|
51
|
+
* down. Rather than reimplement its rules about blank strings, non-string values
|
|
52
|
+
* and what counts as declared, this hands it the node with only the children
|
|
53
|
+
* that are nobody else's, which is exactly the part's own contribution.
|
|
54
|
+
*/
|
|
55
|
+
export declare const ownCopy: (node: ElementNode, declarations: CopyDeclarations) => NodeCopy;
|
|
56
|
+
//# sourceMappingURL=join.d.ts.map
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { PRIMITIVE_ROLES } from "../role.js";
|
|
2
|
+
import { copyIn } from "../sdk/copy.js";
|
|
3
|
+
/**
|
|
4
|
+
* A type's role, inverted from the vocabulary once per reading.
|
|
5
|
+
*
|
|
6
|
+
* Linear in the vocabulary rather than per part: the alternative is asking
|
|
7
|
+
* `typesWithRole` for every part, which is a registry call and a list scan per
|
|
8
|
+
* node on a page that may have thousands.
|
|
9
|
+
*/
|
|
10
|
+
export const rolesByType = (declarations) => {
|
|
11
|
+
const byType = new Map();
|
|
12
|
+
for (const role of PRIMITIVE_ROLES) {
|
|
13
|
+
for (const type of declarations.typesWithRole(role)) {
|
|
14
|
+
/**
|
|
15
|
+
* First declaration wins, and it cannot legitimately happen twice: a
|
|
16
|
+
* definition carries one `role`. A registry that answered the same type
|
|
17
|
+
* for two roles is wrong about something this reading cannot fix, and
|
|
18
|
+
* picking the earlier keeps the answer stable rather than dependent on
|
|
19
|
+
* the vocabulary's order.
|
|
20
|
+
*/
|
|
21
|
+
if (!byType.has(type))
|
|
22
|
+
byType.set(type, role);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
return byType;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* The children that are not parts in their own right, which is what a node
|
|
29
|
+
* contributes itself.
|
|
30
|
+
*
|
|
31
|
+
* Text is kept and an element is dropped, because every element is a part of
|
|
32
|
+
* this reading and would otherwise be counted at two depths. **A slot is kept
|
|
33
|
+
* and pruned the same way**, because a slot is not an element and so is never a
|
|
34
|
+
* part: text handed into one belongs to the nearest element above it, and a slot
|
|
35
|
+
* treated as an element would lose those words to a node this reading never
|
|
36
|
+
* reports. The words of a page are partitioned across its parts exactly once,
|
|
37
|
+
* and that sentence is only true with this clause in it.
|
|
38
|
+
*/
|
|
39
|
+
const ownChildren = (children) => children.flatMap((child) => {
|
|
40
|
+
switch (child.kind) {
|
|
41
|
+
case "element":
|
|
42
|
+
return [];
|
|
43
|
+
case "text":
|
|
44
|
+
return [child];
|
|
45
|
+
case "slot":
|
|
46
|
+
return [{ ...child, children: ownChildren(child.children) }];
|
|
47
|
+
}
|
|
48
|
+
});
|
|
49
|
+
/**
|
|
50
|
+
* What a part says on its own, read with `copyIn` against a node stripped of
|
|
51
|
+
* everything that is a part in its own right.
|
|
52
|
+
*
|
|
53
|
+
* `copyIn` walks a subtree, which is right for its callers and wrong here — a
|
|
54
|
+
* root would carry every word on the page and so would every band on the way
|
|
55
|
+
* down. Rather than reimplement its rules about blank strings, non-string values
|
|
56
|
+
* and what counts as declared, this hands it the node with only the children
|
|
57
|
+
* that are nobody else's, which is exactly the part's own contribution.
|
|
58
|
+
*/
|
|
59
|
+
export const ownCopy = (node, declarations) => copyIn({ ...node, children: ownChildren(node.children) }, declarations);
|
|
60
|
+
//# sourceMappingURL=join.js.map
|
|
@@ -1,15 +1,32 @@
|
|
|
1
|
+
import type { AudienceId } from "../audience/audience.js";
|
|
1
2
|
import type { TreeId } from "../ids.js";
|
|
2
3
|
import { type PageDirection, type PageEnds } from "../paging.js";
|
|
3
4
|
import type { Result } from "../result.js";
|
|
4
|
-
import type { ReaderSignalBatch } from "./signal.js";
|
|
5
|
+
import type { ReaderSignalBatch, ViewKey } from "./signal.js";
|
|
5
6
|
/**
|
|
6
|
-
* Where
|
|
7
|
+
* Where deliveries wait to be rolled up, and then where they are kept.
|
|
7
8
|
*
|
|
8
|
-
*
|
|
9
|
-
* that
|
|
10
|
-
* long as it
|
|
11
|
-
*
|
|
12
|
-
*
|
|
9
|
+
* It was a **buffer, not an archive**, and until 5 November everything about it
|
|
10
|
+
* followed from that: aggregates are the durable artefact (0146), and a raw
|
|
11
|
+
* batch existed for as long as it took rollup to read it and no longer. That is
|
|
12
|
+
* now two lifetimes rather than one
|
|
13
|
+
* ([0351](../../decisions/0351-a-counted-delivery-is-kept-for-a-stated-window-rather-than-deleted-by-the-fold.md),
|
|
14
|
+
* and the policy it serves,
|
|
15
|
+
* [0349](../../decisions/0349-a-projects-reader-events-are-kept-thirty-days-by-default-and-the-tallies-stay-the-durable-record.md)):
|
|
16
|
+
* a delivery is **counted** when it ripens and **deleted** when it is past the
|
|
17
|
+
* window its deployment keeps events for, thirty days by default.
|
|
18
|
+
*
|
|
19
|
+
* **The aggregates are still the durable record.** Nothing read over all time
|
|
20
|
+
* comes out of this table; what the kept window buys is that an operator can
|
|
21
|
+
* look at individual deliveries for as long as it lasts, which is what
|
|
22
|
+
* `docs/portal.md`'s *Events* tab is. Everything a counter answers, a counter
|
|
23
|
+
* goes on answering after the row is gone.
|
|
24
|
+
*
|
|
25
|
+
* So there are two positions in this table rather than one, and they move
|
|
26
|
+
* independently: {@link ReaderSignalJournal.counted} stamps the fold's
|
|
27
|
+
* instant on a prefix, and {@link ReaderSignalJournal.forget} deletes one.
|
|
28
|
+
* **Nothing may delete a row the fold has not stamped** — that rule lives in
|
|
29
|
+
* `expire.ts`, which is the only caller that deletes.
|
|
13
30
|
*
|
|
14
31
|
* It is deliberately the same shape as `src/telemetry/journal.ts` — append,
|
|
15
32
|
* page by an opaque cursor, forget a prefix — because a second paged log that
|
|
@@ -17,7 +34,10 @@ import type { ReaderSignalBatch } from "./signal.js";
|
|
|
17
34
|
* cursor rules to be subtly wrong. What it is not is the same *table*: a
|
|
18
35
|
* journal holds what the runtime said about itself, and this holds what
|
|
19
36
|
* browsers said about pages, and the two have different retention and different
|
|
20
|
-
* volumes by two orders of magnitude.
|
|
37
|
+
* volumes by two orders of magnitude. The fourth operation is where the two
|
|
38
|
+
* shapes part company, and it is the retention rule that asked for it: a
|
|
39
|
+
* telemetry episode is deleted by age alone, and a delivery may not be deleted
|
|
40
|
+
* until it has been counted.
|
|
21
41
|
*/
|
|
22
42
|
/**
|
|
23
43
|
* The only way it fails. No `not-found` — reading a tree nothing has been
|
|
@@ -40,10 +60,67 @@ export declare const describeReaderSignalStoreError: (error: ReaderSignalStoreEr
|
|
|
40
60
|
export type ReceivedBatch = ReaderSignalBatch & {
|
|
41
61
|
readonly seq: number;
|
|
42
62
|
readonly receivedAt: string;
|
|
63
|
+
/**
|
|
64
|
+
* The audience it was **filed** under, which is resolved rather than
|
|
65
|
+
* optional (0284).
|
|
66
|
+
*
|
|
67
|
+
* `audience` is what the sender said and may be absent; this is what the
|
|
68
|
+
* buffer stored, and a stored row always names one — `aud_everyone` where the
|
|
69
|
+
* sender named nothing. A fold reads this, so that a window holding two
|
|
70
|
+
* audiences folds into two sets of counters rather than one.
|
|
71
|
+
*/
|
|
72
|
+
readonly audienceId: AudienceId;
|
|
73
|
+
/**
|
|
74
|
+
* When a fold counted this delivery into the counters, where one has (0351).
|
|
75
|
+
*
|
|
76
|
+
* Absent is *not yet counted*, which is what every row in the table used to
|
|
77
|
+
* be: before the kept window existed a counted delivery was deleted in the
|
|
78
|
+
* same operation, so there was no state to record. It is the only field on a
|
|
79
|
+
* stored row that changes after it is written, and only one writer sets it.
|
|
80
|
+
*
|
|
81
|
+
* **It is the fold's own instant, not the row's age.** `receivedAt` is what
|
|
82
|
+
* retention measures and this is what makes a row eligible for it — a
|
|
83
|
+
* delivery is deleted when it is both past the kept window and stamped here,
|
|
84
|
+
* never on one of the two (`expire.ts`).
|
|
85
|
+
*/
|
|
86
|
+
readonly foldedAt?: string;
|
|
43
87
|
};
|
|
44
88
|
export type ReaderSignalReadRequest = {
|
|
45
89
|
/** Absent reads every tree the handle can see, which is the scope rule (0020). */
|
|
46
90
|
readonly treeId?: TreeId;
|
|
91
|
+
/**
|
|
92
|
+
* Narrow to rows the fold has counted, or to rows it has not.
|
|
93
|
+
*
|
|
94
|
+
* Absent reads both, which is what a surface listing deliveries wants and
|
|
95
|
+
* what every caller wanted when a counted row did not outlive its fold.
|
|
96
|
+
*
|
|
97
|
+
* **`false` is the collection scan's read and the reason this exists.** The
|
|
98
|
+
* scan runs from the oldest end looking for the oldest ripe delivery, and the
|
|
99
|
+
* oldest end of a table that keeps deliveries for thirty days is thirty days
|
|
100
|
+
* of rows that have already been counted. Without the filter, collection's
|
|
101
|
+
* cost would grow with the kept window rather than with the window it folds
|
|
102
|
+
* — and the kept window is the one a deployment is invited to lengthen.
|
|
103
|
+
*/
|
|
104
|
+
readonly counted?: boolean;
|
|
105
|
+
/**
|
|
106
|
+
* Narrow to the deliveries of **one page view**, named by its key (0355).
|
|
107
|
+
*
|
|
108
|
+
* The one correlation the subsystem allows, and the whole of it: a caller
|
|
109
|
+
* hands in a key it is already holding — off a row it could already see —
|
|
110
|
+
* and gets that page view's deliveries. There is deliberately nothing here
|
|
111
|
+
* that would **enumerate** keys, and nothing that takes a row and asks *what
|
|
112
|
+
* else shares this one's key*, because either of those is a stitching
|
|
113
|
+
* primitive wearing a narrowing's clothes. One key in, one page view out.
|
|
114
|
+
*
|
|
115
|
+
* It is a filter rather than a second method so that the paging rules are the
|
|
116
|
+
* ones this request already has. A page view holds few deliveries, but *few*
|
|
117
|
+
* is a sender's choice rather than a bound, so the read that serves a drawer
|
|
118
|
+
* is a page like every other read here.
|
|
119
|
+
*
|
|
120
|
+
* Served by a partial index on the column, which exists because a delivery
|
|
121
|
+
* that names no page view is never looked up by one.
|
|
122
|
+
*/
|
|
123
|
+
readonly view?: ViewKey;
|
|
47
124
|
/** A cursor from a previous page's `older`/`newer`, passed back unread. */
|
|
48
125
|
readonly cursor?: string;
|
|
49
126
|
/** Default `newer`, which with no cursor is the oldest page — where rollup starts. */
|
|
@@ -78,7 +155,36 @@ export type ForgetOutcome = {
|
|
|
78
155
|
readonly removed: number;
|
|
79
156
|
};
|
|
80
157
|
/**
|
|
81
|
-
*
|
|
158
|
+
* What the fold is asked to stamp, as a position and the instant to write.
|
|
159
|
+
*
|
|
160
|
+
* The same prefix shape {@link ForgetBefore} takes, because it replaces that
|
|
161
|
+
* call in the one place a fold used to make it: counting and dropping were one
|
|
162
|
+
* operation and are now counting and *marking*, which is the same operation
|
|
163
|
+
* against a table that keeps the row (0351).
|
|
164
|
+
*
|
|
165
|
+
* The instant is the fold's, handed in rather than read from a clock here, for
|
|
166
|
+
* the reason every other stored timestamp in this subsystem is handed in: a run
|
|
167
|
+
* writes one instant across every row and every counter it touches, and a store
|
|
168
|
+
* that read its own clock would stamp rows a run did not think it was stamping.
|
|
169
|
+
*/
|
|
170
|
+
export type CountedBefore = {
|
|
171
|
+
readonly before: number;
|
|
172
|
+
readonly at: string;
|
|
173
|
+
};
|
|
174
|
+
export type CountedOutcome = {
|
|
175
|
+
/**
|
|
176
|
+
* Rows this call stamped.
|
|
177
|
+
*
|
|
178
|
+
* Only rows that carried nothing: a row already stamped is left exactly as it
|
|
179
|
+
* was, so a second run over the same prefix reports nought rather than moving
|
|
180
|
+
* an instant that a reading has already been taken against. It is what makes
|
|
181
|
+
* this operation safe to repeat, which matters because the run that makes it
|
|
182
|
+
* is the run that has already made the counters durable.
|
|
183
|
+
*/
|
|
184
|
+
readonly counted: number;
|
|
185
|
+
};
|
|
186
|
+
/**
|
|
187
|
+
* Four operations: the journal's three, and the stamp the kept window asked for.
|
|
82
188
|
*
|
|
83
189
|
* `receive` takes several batches because an ingestion endpoint may be handed
|
|
84
190
|
* several and should pay for one round trip. Unlike a journal's, this batch has
|
|
@@ -89,6 +195,14 @@ export type ForgetOutcome = {
|
|
|
89
195
|
export interface ReaderSignalJournal {
|
|
90
196
|
readonly receive: (batches: readonly ReaderSignalBatch[]) => Promise<Result<void, ReaderSignalStoreError>>;
|
|
91
197
|
readonly read: (request?: ReaderSignalReadRequest) => Promise<Result<ReaderSignalPage, ReaderSignalStoreError>>;
|
|
198
|
+
/**
|
|
199
|
+
* Record that a fold counted every row below a position (0351).
|
|
200
|
+
*
|
|
201
|
+
* Idempotent by construction — it stamps only what carries nothing — because
|
|
202
|
+
* the caller has already written the counters when it gets here, so the one
|
|
203
|
+
* thing it must never do is make a retry worse than the failure.
|
|
204
|
+
*/
|
|
205
|
+
readonly counted: (request: CountedBefore) => Promise<Result<CountedOutcome, ReaderSignalStoreError>>;
|
|
92
206
|
readonly forget: (request: ForgetBefore) => Promise<Result<ForgetOutcome, ReaderSignalStoreError>>;
|
|
93
207
|
}
|
|
94
208
|
//# sourceMappingURL=journal.d.ts.map
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fifth contract suite both reader-signal journals are run against: **a
|
|
3
|
+
* counted delivery is marked rather than deleted, and the mark is what the next
|
|
4
|
+
* fold reads** (0351).
|
|
5
|
+
*
|
|
6
|
+
* It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
|
|
7
|
+
* for the reason `applied-window.contract.ts` is: that directory is another
|
|
8
|
+
* lane's and this is reader-signal work. The finding filed with 0316 asks for
|
|
9
|
+
* the set to be moved together, which is one import away.
|
|
10
|
+
*
|
|
11
|
+
* **Every property here needs two implementations to be worth asserting**,
|
|
12
|
+
* which is what earns it a contract rather than a test beside the memory store.
|
|
13
|
+
* The stamp has to be idempotent, and in Postgres that is a clause in a `WHERE`
|
|
14
|
+
* — `folded_at IS NULL` — while in memory it is a guard in a `map`. The filter
|
|
15
|
+
* has to tell three states apart, and in Postgres `null` is one of them while
|
|
16
|
+
* in memory the field is absent. Those are exactly the differences that make
|
|
17
|
+
* two stores quietly disagree, and the disagreement here would be a window
|
|
18
|
+
* counted twice (0158).
|
|
19
|
+
*/
|
|
20
|
+
import type { ReaderSignalJournal } from "./journal.js";
|
|
21
|
+
export declare const describeKeptDeliveryContract: (name: string, make: () => Promise<ReaderSignalJournal> | ReaderSignalJournal) => void;
|
|
22
|
+
//# sourceMappingURL=kept.contract.d.ts.map
|