@jam-overture/loom 0.1.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/LICENSE +21 -0
- package/README.md +743 -0
- package/dist/catalogue.d.ts +70 -0
- package/dist/catalogue.js +88 -0
- package/dist/cli/args.d.ts +17 -0
- package/dist/cli/args.js +83 -0
- package/dist/cli/filesystem.d.ts +15 -0
- package/dist/cli/filesystem.js +31 -0
- package/dist/cli/index.d.ts +12 -0
- package/dist/cli/index.js +12 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +30 -0
- package/dist/cli/namespace.d.ts +40 -0
- package/dist/cli/namespace.js +40 -0
- package/dist/cli/plan.d.ts +84 -0
- package/dist/cli/plan.js +113 -0
- package/dist/cli/run.d.ts +17 -0
- package/dist/cli/run.js +75 -0
- package/dist/cli/templates.d.ts +43 -0
- package/dist/cli/templates.js +134 -0
- package/dist/closed-set.d.ts +34 -0
- package/dist/closed-set.js +34 -0
- package/dist/data/adapter.d.ts +123 -0
- package/dist/data/adapter.js +91 -0
- package/dist/data/binding.d.ts +48 -0
- package/dist/data/binding.js +39 -0
- package/dist/data/catalogue.d.ts +26 -0
- package/dist/data/catalogue.js +6 -0
- package/dist/data/index.d.ts +14 -0
- package/dist/data/index.js +14 -0
- package/dist/data/plan.d.ts +58 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +91 -0
- package/dist/data/resolution.js +96 -0
- package/dist/data/resolve.d.ts +46 -0
- package/dist/data/resolve.js +37 -0
- package/dist/data/source.d.ts +40 -0
- package/dist/data/source.js +45 -0
- package/dist/deadline.d.ts +57 -0
- package/dist/deadline.js +78 -0
- package/dist/frame/catalogue.d.ts +24 -0
- package/dist/frame/catalogue.js +5 -0
- package/dist/frame/index.d.ts +12 -0
- package/dist/frame/index.js +12 -0
- package/dist/frame/origin.d.ts +87 -0
- package/dist/frame/origin.js +114 -0
- package/dist/frame/resolution.d.ts +85 -0
- package/dist/frame/resolution.js +79 -0
- package/dist/grammar.d.ts +26 -0
- package/dist/grammar.js +28 -0
- package/dist/ids.d.ts +57 -0
- package/dist/ids.js +104 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/interactivity.d.ts +50 -0
- package/dist/interactivity.js +22 -0
- package/dist/interpretation/anthropic.d.ts +22 -0
- package/dist/interpretation/anthropic.js +76 -0
- package/dist/interpretation/client.d.ts +83 -0
- package/dist/interpretation/client.js +2 -0
- package/dist/interpretation/draft.d.ts +234 -0
- package/dist/interpretation/draft.js +84 -0
- package/dist/interpretation/index.d.ts +15 -0
- package/dist/interpretation/index.js +15 -0
- package/dist/interpretation/interpreter.d.ts +62 -0
- package/dist/interpretation/interpreter.js +151 -0
- package/dist/interpretation/materialize.d.ts +42 -0
- package/dist/interpretation/materialize.js +107 -0
- package/dist/interpretation/prompt.d.ts +229 -0
- package/dist/interpretation/prompt.js +285 -0
- package/dist/interpretation/render.d.ts +76 -0
- package/dist/interpretation/render.js +272 -0
- package/dist/interpretation/schema.d.ts +49 -0
- package/dist/interpretation/schema.js +131 -0
- package/dist/json.d.ts +35 -0
- package/dist/json.js +11 -0
- package/dist/paging.d.ts +60 -0
- package/dist/paging.js +49 -0
- package/dist/primitive-type.d.ts +32 -0
- package/dist/primitive-type.js +39 -0
- package/dist/render/addressing.d.ts +59 -0
- package/dist/render/addressing.js +60 -0
- package/dist/render/anchor.d.ts +105 -0
- package/dist/render/anchor.js +84 -0
- package/dist/render/behaviour-adjust.d.ts +62 -0
- package/dist/render/behaviour-adjust.js +78 -0
- package/dist/render/behaviour-copy.d.ts +53 -0
- package/dist/render/behaviour-copy.js +75 -0
- package/dist/render/behaviour-disclose.d.ts +74 -0
- package/dist/render/behaviour-disclose.js +77 -0
- package/dist/render/behaviour-present.d.ts +123 -0
- package/dist/render/behaviour-present.js +173 -0
- package/dist/render/behaviour.d.ts +243 -0
- package/dist/render/behaviour.js +284 -0
- package/dist/render/control.d.ts +81 -0
- package/dist/render/control.js +80 -0
- package/dist/render/decorative.d.ts +62 -0
- package/dist/render/decorative.js +2 -0
- package/dist/render/diagnostics.d.ts +260 -0
- package/dist/render/diagnostics.js +61 -0
- package/dist/render/disclosed.d.ts +37 -0
- package/dist/render/disclosed.js +37 -0
- package/dist/render/editable.d.ts +34 -0
- package/dist/render/editable.js +35 -0
- package/dist/render/frame.d.ts +42 -0
- package/dist/render/frame.js +31 -0
- package/dist/render/index.d.ts +35 -0
- package/dist/render/index.js +35 -0
- package/dist/render/inline-variables.d.ts +77 -0
- package/dist/render/inline-variables.js +220 -0
- package/dist/render/presented.d.ts +82 -0
- package/dist/render/presented.js +82 -0
- package/dist/render/primitive.d.ts +228 -0
- package/dist/render/primitive.js +36 -0
- package/dist/render/props.d.ts +48 -0
- package/dist/render/props.js +2 -0
- package/dist/render/reads.d.ts +73 -0
- package/dist/render/reads.js +45 -0
- package/dist/render/render.d.ts +164 -0
- package/dist/render/render.js +571 -0
- package/dist/render/request.d.ts +111 -0
- package/dist/render/request.js +60 -0
- package/dist/render/text.d.ts +91 -0
- package/dist/render/text.js +44 -0
- package/dist/render/theme.d.ts +61 -0
- package/dist/render/theme.js +52 -0
- package/dist/reserved-props.d.ts +35 -0
- package/dist/reserved-props.js +45 -0
- package/dist/result.d.ts +27 -0
- package/dist/result.js +30 -0
- package/dist/role.d.ts +71 -0
- package/dist/role.js +22 -0
- package/dist/runtime/analysis.d.ts +149 -0
- package/dist/runtime/analysis.js +187 -0
- package/dist/runtime/assessment.d.ts +35 -0
- package/dist/runtime/assessment.js +13 -0
- package/dist/runtime/disposition.d.ts +102 -0
- package/dist/runtime/disposition.js +59 -0
- package/dist/runtime/events.d.ts +187 -0
- package/dist/runtime/events.js +7 -0
- package/dist/runtime/gate.d.ts +43 -0
- package/dist/runtime/gate.js +169 -0
- package/dist/runtime/index.d.ts +27 -0
- package/dist/runtime/index.js +27 -0
- package/dist/runtime/intent.d.ts +60 -0
- package/dist/runtime/intent.js +36 -0
- package/dist/runtime/interpreter.d.ts +117 -0
- package/dist/runtime/interpreter.js +46 -0
- package/dist/runtime/inverse-interpreter.d.ts +90 -0
- package/dist/runtime/inverse-interpreter.js +56 -0
- package/dist/runtime/inverse.d.ts +87 -0
- package/dist/runtime/inverse.js +48 -0
- package/dist/runtime/narration.d.ts +24 -0
- package/dist/runtime/narration.js +36 -0
- package/dist/runtime/nesting.d.ts +31 -0
- package/dist/runtime/nesting.js +46 -0
- package/dist/runtime/pipeline.d.ts +124 -0
- package/dist/runtime/pipeline.js +178 -0
- package/dist/runtime/policy-fingerprint.d.ts +29 -0
- package/dist/runtime/policy-fingerprint.js +119 -0
- package/dist/runtime/policy-source.d.ts +42 -0
- package/dist/runtime/policy-source.js +8 -0
- package/dist/runtime/policy.d.ts +156 -0
- package/dist/runtime/policy.js +107 -0
- package/dist/runtime/proposal.d.ts +423 -0
- package/dist/runtime/proposal.js +109 -0
- package/dist/runtime/redirection.d.ts +53 -0
- package/dist/runtime/redirection.js +38 -0
- package/dist/runtime/repointing.d.ts +71 -0
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +36 -0
- package/dist/runtime/reversibility.js +39 -0
- package/dist/runtime/stake-level.d.ts +33 -0
- package/dist/runtime/stake-level.js +58 -0
- package/dist/runtime/stakes.d.ts +47 -0
- package/dist/runtime/stakes.js +305 -0
- package/dist/runtime/vocabulary.d.ts +122 -0
- package/dist/runtime/vocabulary.js +87 -0
- package/dist/sdk/audit.d.ts +195 -0
- package/dist/sdk/audit.js +128 -0
- package/dist/sdk/catalogue.d.ts +37 -0
- package/dist/sdk/catalogue.js +16 -0
- package/dist/sdk/conformance.d.ts +342 -0
- package/dist/sdk/conformance.js +494 -0
- package/dist/sdk/copy.d.ts +105 -0
- package/dist/sdk/copy.js +90 -0
- package/dist/sdk/definition.d.ts +242 -0
- package/dist/sdk/definition.js +64 -0
- package/dist/sdk/index.d.ts +19 -0
- package/dist/sdk/index.js +19 -0
- package/dist/sdk/interactivity.d.ts +29 -0
- package/dist/sdk/interactivity.js +34 -0
- package/dist/sdk/pairings.d.ts +124 -0
- package/dist/sdk/pairings.js +81 -0
- package/dist/sdk/registry.d.ts +162 -0
- package/dist/sdk/registry.js +329 -0
- package/dist/sdk/selection.d.ts +46 -0
- package/dist/sdk/selection.js +24 -0
- package/dist/sdk/text.d.ts +100 -0
- package/dist/sdk/text.js +105 -0
- package/dist/sdk/vocabulary.d.ts +39 -0
- package/dist/sdk/vocabulary.js +36 -0
- package/dist/signals/broadcast.d.ts +134 -0
- package/dist/signals/broadcast.js +451 -0
- package/dist/signals/collect.d.ts +184 -0
- package/dist/signals/collect.js +196 -0
- package/dist/signals/deliver.d.ts +64 -0
- package/dist/signals/deliver.js +85 -0
- package/dist/signals/fold.d.ts +112 -0
- package/dist/signals/fold.js +76 -0
- package/dist/signals/index.d.ts +31 -0
- package/dist/signals/index.js +31 -0
- package/dist/signals/ingest.d.ts +51 -0
- package/dist/signals/ingest.js +70 -0
- package/dist/signals/intake.d.ts +149 -0
- package/dist/signals/intake.js +154 -0
- package/dist/signals/journal.d.ts +94 -0
- package/dist/signals/journal.js +11 -0
- package/dist/signals/kinds.d.ts +22 -0
- package/dist/signals/kinds.js +22 -0
- package/dist/signals/ledger.d.ts +46 -0
- package/dist/signals/ledger.js +81 -0
- package/dist/signals/memory.d.ts +17 -0
- package/dist/signals/memory.js +99 -0
- package/dist/signals/migrate.d.ts +27 -0
- package/dist/signals/migrate.js +78 -0
- package/dist/signals/postgres.d.ts +7 -0
- package/dist/signals/postgres.js +295 -0
- package/dist/signals/rollup.d.ts +142 -0
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +534 -0
- package/dist/signals/schema.js +92 -0
- package/dist/signals/signal.d.ts +381 -0
- package/dist/signals/signal.js +150 -0
- package/dist/signals/tally.d.ts +70 -0
- package/dist/signals/tally.js +2 -0
- package/dist/signals/view.d.ts +51 -0
- package/dist/signals/view.js +54 -0
- package/dist/store/attribution.d.ts +125 -0
- package/dist/store/attribution.js +116 -0
- package/dist/store/database.d.ts +14 -0
- package/dist/store/database.js +2 -0
- package/dist/store/driver.d.ts +29 -0
- package/dist/store/driver.js +39 -0
- package/dist/store/errors.d.ts +56 -0
- package/dist/store/errors.js +37 -0
- package/dist/store/index.d.ts +16 -0
- package/dist/store/index.js +16 -0
- package/dist/store/memory.d.ts +3 -0
- package/dist/store/memory.js +115 -0
- package/dist/store/migrate.d.ts +54 -0
- package/dist/store/migrate.js +122 -0
- package/dist/store/postgres-holds.d.ts +4 -0
- package/dist/store/postgres-holds.js +192 -0
- package/dist/store/postgres.d.ts +8 -0
- package/dist/store/postgres.js +262 -0
- package/dist/store/replay.d.ts +94 -0
- package/dist/store/replay.js +82 -0
- package/dist/store/revert.d.ts +116 -0
- package/dist/store/revert.js +243 -0
- package/dist/store/schema.d.ts +371 -0
- package/dist/store/schema.js +78 -0
- package/dist/store/source.d.ts +23 -0
- package/dist/store/source.js +37 -0
- package/dist/store/store.d.ts +231 -0
- package/dist/store/store.js +52 -0
- package/dist/store/undone.d.ts +18 -0
- package/dist/store/undone.js +89 -0
- package/dist/submit/catalogue.d.ts +20 -0
- package/dist/submit/catalogue.js +5 -0
- package/dist/submit/declaration.d.ts +39 -0
- package/dist/submit/declaration.js +30 -0
- package/dist/submit/endpoint.d.ts +131 -0
- package/dist/submit/endpoint.js +160 -0
- package/dist/submit/index.d.ts +13 -0
- package/dist/submit/index.js +13 -0
- package/dist/submit/plan.d.ts +49 -0
- package/dist/submit/plan.js +47 -0
- package/dist/submit/resolution.d.ts +61 -0
- package/dist/submit/resolution.js +64 -0
- package/dist/submit/resolve.d.ts +45 -0
- package/dist/submit/resolve.js +36 -0
- package/dist/telemetry/calibration.d.ts +132 -0
- package/dist/telemetry/calibration.js +151 -0
- package/dist/telemetry/episode.d.ts +140 -0
- package/dist/telemetry/episode.js +272 -0
- package/dist/telemetry/event.d.ts +2310 -0
- package/dist/telemetry/event.js +405 -0
- package/dist/telemetry/index.d.ts +15 -0
- package/dist/telemetry/index.js +15 -0
- package/dist/telemetry/journal.d.ts +116 -0
- package/dist/telemetry/journal.js +11 -0
- package/dist/telemetry/memory.d.ts +24 -0
- package/dist/telemetry/memory.js +75 -0
- package/dist/telemetry/migrate.d.ts +26 -0
- package/dist/telemetry/migrate.js +40 -0
- package/dist/telemetry/postgres.d.ts +6 -0
- package/dist/telemetry/postgres.js +139 -0
- package/dist/telemetry/retention.d.ts +131 -0
- package/dist/telemetry/retention.js +217 -0
- package/dist/telemetry/schema.d.ts +113 -0
- package/dist/telemetry/schema.js +33 -0
- package/dist/telemetry/sink.d.ts +42 -0
- package/dist/telemetry/sink.js +61 -0
- package/dist/testing/contracts.d.ts +34 -0
- package/dist/testing/contracts.js +34 -0
- package/dist/testing/definitions.d.ts +15 -0
- package/dist/testing/definitions.js +48 -0
- package/dist/testing/doubles.d.ts +94 -0
- package/dist/testing/doubles.js +141 -0
- package/dist/testing/episode-harness.d.ts +49 -0
- package/dist/testing/episode-harness.js +65 -0
- package/dist/testing/filesystem.d.ts +17 -0
- package/dist/testing/filesystem.js +17 -0
- package/dist/testing/fixtures.d.ts +57 -0
- package/dist/testing/fixtures.js +84 -0
- package/dist/testing/hold-contract.d.ts +19 -0
- package/dist/testing/hold-contract.js +374 -0
- package/dist/testing/index.d.ts +41 -0
- package/dist/testing/index.js +41 -0
- package/dist/testing/journal-contract.d.ts +17 -0
- package/dist/testing/journal-contract.js +353 -0
- package/dist/testing/model-replies.d.ts +34 -0
- package/dist/testing/model-replies.js +101 -0
- package/dist/testing/primitives.d.ts +7 -0
- package/dist/testing/primitives.js +29 -0
- package/dist/testing/reader-signal-contract.d.ts +38 -0
- package/dist/testing/reader-signal-contract.js +318 -0
- package/dist/testing/row-security.d.ts +17 -0
- package/dist/testing/row-security.js +21 -0
- package/dist/testing/store-contract.d.ts +25 -0
- package/dist/testing/store-contract.js +500 -0
- package/dist/theme/apply.d.ts +17 -0
- package/dist/theme/apply.js +60 -0
- package/dist/theme/contrast.d.ts +197 -0
- package/dist/theme/contrast.js +259 -0
- package/dist/theme/derive.d.ts +77 -0
- package/dist/theme/derive.js +167 -0
- package/dist/theme/faces.d.ts +73 -0
- package/dist/theme/faces.js +119 -0
- package/dist/theme/font-packs.d.ts +25 -0
- package/dist/theme/font-packs.js +257 -0
- package/dist/theme/index.d.ts +20 -0
- package/dist/theme/index.js +20 -0
- package/dist/theme/lab.d.ts +30 -0
- package/dist/theme/lab.js +46 -0
- package/dist/theme/library.d.ts +114 -0
- package/dist/theme/library.js +300 -0
- package/dist/theme/measure.d.ts +144 -0
- package/dist/theme/measure.js +145 -0
- package/dist/theme/palettes.d.ts +64 -0
- package/dist/theme/palettes.js +497 -0
- package/dist/theme/registry.d.ts +59 -0
- package/dist/theme/registry.js +60 -0
- package/dist/theme/separation.d.ts +177 -0
- package/dist/theme/separation.js +203 -0
- package/dist/theme/style-presets.d.ts +60 -0
- package/dist/theme/style-presets.js +124 -0
- package/dist/theme/theme.d.ts +253 -0
- package/dist/theme/theme.js +171 -0
- package/dist/tree/apply.d.ts +16 -0
- package/dist/tree/apply.js +104 -0
- package/dist/tree/builders.d.ts +19 -0
- package/dist/tree/builders.js +20 -0
- package/dist/tree/compare.d.ts +68 -0
- package/dist/tree/compare.js +75 -0
- package/dist/tree/configuration.d.ts +25 -0
- package/dist/tree/configuration.js +108 -0
- package/dist/tree/delta.d.ts +288 -0
- package/dist/tree/delta.js +88 -0
- package/dist/tree/errors.d.ts +69 -0
- package/dist/tree/errors.js +34 -0
- package/dist/tree/identity.d.ts +117 -0
- package/dist/tree/identity.js +145 -0
- package/dist/tree/index.d.ts +21 -0
- package/dist/tree/index.js +21 -0
- package/dist/tree/inverse.d.ts +24 -0
- package/dist/tree/inverse.js +112 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +49 -0
- package/dist/tree/naming.d.ts +4 -0
- package/dist/tree/naming.js +35 -0
- package/dist/tree/navigation.d.ts +38 -0
- package/dist/tree/navigation.js +83 -0
- package/dist/tree/node.d.ts +103 -0
- package/dist/tree/node.js +46 -0
- package/dist/tree/outline.d.ts +28 -0
- package/dist/tree/outline.js +10 -0
- package/dist/tree/tree.d.ts +83 -0
- package/dist/tree/tree.js +62 -0
- package/dist/write/commit.d.ts +124 -0
- package/dist/write/commit.js +234 -0
- package/dist/write/held.d.ts +674 -0
- package/dist/write/held.js +185 -0
- package/dist/write/index.d.ts +11 -0
- package/dist/write/index.js +11 -0
- package/dist/write/liveness.d.ts +132 -0
- package/dist/write/liveness.js +91 -0
- package/dist/write/revert.d.ts +79 -0
- package/dist/write/revert.js +134 -0
- package/package.json +160 -0
|
@@ -0,0 +1,381 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { type Result } from "../result.js";
|
|
3
|
+
/**
|
|
4
|
+
* What a published page may say about how it is being read.
|
|
5
|
+
*
|
|
6
|
+
* A reader signal is an observation about one node of one revision of one tree:
|
|
7
|
+
* it came into view, it stayed there this long, a reader activated a target in
|
|
8
|
+
* it, a reader opened or closed it. Nothing more, and deliberately so.
|
|
9
|
+
*
|
|
10
|
+
* **The vocabulary is closed.** Four kinds, for the same reason the operations on
|
|
11
|
+
* a tree are four and the schemes a URL may use are a list (0053): an adaptation
|
|
12
|
+
* is proposed from these, and a stream that may carry anything is a stream
|
|
13
|
+
* nothing can reason about. A kind is added here or it does not exist.
|
|
14
|
+
*
|
|
15
|
+
* **A signal carries no content.** No text a node shows, no URL a link goes to,
|
|
16
|
+
* no value a reader typed, nothing that identifies the reader. The tree already
|
|
17
|
+
* holds the content at the revision the signal names, and a record of what a
|
|
18
|
+
* person read is a record of that person — the rule telemetry already keeps for
|
|
19
|
+
* utterances (0023).
|
|
20
|
+
*
|
|
21
|
+
* **The revision is on every batch.** A signal about "the fourth section" means
|
|
22
|
+
* nothing once a proposal has moved it; a signal about node `n_42` at revision 3
|
|
23
|
+
* means exactly one thing forever (0136).
|
|
24
|
+
*/
|
|
25
|
+
export { DELEGATED_READER_SIGNAL_KINDS, READER_SIGNAL_KINDS } from "./kinds.js";
|
|
26
|
+
export declare const readerSignalKindSchema: z.ZodEnum<["viewed", "dwelled", "activated", "disclosed"]>;
|
|
27
|
+
export type ReaderSignalKind = z.infer<typeof readerSignalKindSchema>;
|
|
28
|
+
/**
|
|
29
|
+
* The key that says two batches came from the same page view, and says nothing
|
|
30
|
+
* else (0146).
|
|
31
|
+
*
|
|
32
|
+
* Branded like an id, but deliberately not one: it is minted by a browser
|
|
33
|
+
* rather than an id factory, it is not stable, nothing may be addressed by it,
|
|
34
|
+
* and it is dropped when the raw window expires. `view.ts` holds the pattern
|
|
35
|
+
* and the minting, because the broadcaster needs both and cannot load this
|
|
36
|
+
* module.
|
|
37
|
+
*/
|
|
38
|
+
export declare const viewKeySchema: z.ZodBranded<z.ZodString, "ViewKey">;
|
|
39
|
+
export type ViewKey = z.infer<typeof viewKeySchema>;
|
|
40
|
+
/**
|
|
41
|
+
* One addressed node, as a signal names it.
|
|
42
|
+
*
|
|
43
|
+
* The same pair `addressSchema` spreads, as a schema of its own, because an
|
|
44
|
+
* ancestry is a list of them.
|
|
45
|
+
*/
|
|
46
|
+
export declare const signalAddressSchema: z.ZodObject<{
|
|
47
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
48
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
49
|
+
}, "strict", z.ZodTypeAny, {
|
|
50
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
51
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
52
|
+
}, {
|
|
53
|
+
type: string;
|
|
54
|
+
nodeId: string;
|
|
55
|
+
}>;
|
|
56
|
+
/**
|
|
57
|
+
* The four kinds.
|
|
58
|
+
*
|
|
59
|
+
* `viewed` fires once per node for the life of the page. `dwelled` is time on
|
|
60
|
+
* screen accumulated since the previous batch, so summing a node's `dwelled` over
|
|
61
|
+
* every batch is its total. `activated` is a reader using a link, button or field
|
|
62
|
+
* inside the node — the node named is the nearest addressed one, which in the
|
|
63
|
+
* starter library is usually the control itself. `disclosed` is a region opened
|
|
64
|
+
* or closed.
|
|
65
|
+
*
|
|
66
|
+
* Those last two are `DELEGATED_READER_SIGNAL_KINDS`: what a reader aimed at is
|
|
67
|
+
* a control, and the region it sits in is a question nothing else can answer
|
|
68
|
+
* afterwards, so they carry `within` and the other two do not.
|
|
69
|
+
*/
|
|
70
|
+
export declare const readerSignalSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
|
|
71
|
+
at: z.ZodNumber;
|
|
72
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
73
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
74
|
+
kind: z.ZodLiteral<"viewed">;
|
|
75
|
+
}, "strict", z.ZodTypeAny, {
|
|
76
|
+
at: number;
|
|
77
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
78
|
+
kind: "viewed";
|
|
79
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
80
|
+
}, {
|
|
81
|
+
at: number;
|
|
82
|
+
type: string;
|
|
83
|
+
kind: "viewed";
|
|
84
|
+
nodeId: string;
|
|
85
|
+
}>, z.ZodObject<{
|
|
86
|
+
ms: z.ZodNumber;
|
|
87
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
88
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
89
|
+
kind: z.ZodLiteral<"dwelled">;
|
|
90
|
+
}, "strict", z.ZodTypeAny, {
|
|
91
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
92
|
+
kind: "dwelled";
|
|
93
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
94
|
+
ms: number;
|
|
95
|
+
}, {
|
|
96
|
+
type: string;
|
|
97
|
+
kind: "dwelled";
|
|
98
|
+
nodeId: string;
|
|
99
|
+
ms: number;
|
|
100
|
+
}>, z.ZodObject<{
|
|
101
|
+
at: z.ZodNumber;
|
|
102
|
+
within: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
|
|
103
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
104
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
105
|
+
}, "strict", z.ZodTypeAny, {
|
|
106
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
107
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
108
|
+
}, {
|
|
109
|
+
type: string;
|
|
110
|
+
nodeId: string;
|
|
111
|
+
}>, "many">>>;
|
|
112
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
113
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
114
|
+
kind: z.ZodLiteral<"activated">;
|
|
115
|
+
}, "strict", z.ZodTypeAny, {
|
|
116
|
+
at: number;
|
|
117
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
118
|
+
kind: "activated";
|
|
119
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
120
|
+
within?: readonly {
|
|
121
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
122
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
123
|
+
}[] | undefined;
|
|
124
|
+
}, {
|
|
125
|
+
at: number;
|
|
126
|
+
type: string;
|
|
127
|
+
kind: "activated";
|
|
128
|
+
nodeId: string;
|
|
129
|
+
within?: readonly {
|
|
130
|
+
type: string;
|
|
131
|
+
nodeId: string;
|
|
132
|
+
}[] | undefined;
|
|
133
|
+
}>, z.ZodObject<{
|
|
134
|
+
open: z.ZodBoolean;
|
|
135
|
+
at: z.ZodNumber;
|
|
136
|
+
within: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
|
|
137
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
138
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
139
|
+
}, "strict", z.ZodTypeAny, {
|
|
140
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
141
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
142
|
+
}, {
|
|
143
|
+
type: string;
|
|
144
|
+
nodeId: string;
|
|
145
|
+
}>, "many">>>;
|
|
146
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
147
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
148
|
+
kind: z.ZodLiteral<"disclosed">;
|
|
149
|
+
}, "strict", z.ZodTypeAny, {
|
|
150
|
+
at: number;
|
|
151
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
152
|
+
kind: "disclosed";
|
|
153
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
154
|
+
open: boolean;
|
|
155
|
+
within?: readonly {
|
|
156
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
157
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
158
|
+
}[] | undefined;
|
|
159
|
+
}, {
|
|
160
|
+
at: number;
|
|
161
|
+
type: string;
|
|
162
|
+
kind: "disclosed";
|
|
163
|
+
nodeId: string;
|
|
164
|
+
open: boolean;
|
|
165
|
+
within?: readonly {
|
|
166
|
+
type: string;
|
|
167
|
+
nodeId: string;
|
|
168
|
+
}[] | undefined;
|
|
169
|
+
}>]>;
|
|
170
|
+
export type ReaderSignal = z.infer<typeof readerSignalSchema>;
|
|
171
|
+
/**
|
|
172
|
+
* One delivery: the signals a page gathered since the last one, all about the
|
|
173
|
+
* same tree at the same revision.
|
|
174
|
+
*
|
|
175
|
+
* The tree and revision sit on the batch rather than on each signal because a
|
|
176
|
+
* rendered page is one revision of one tree — they cannot differ inside a batch,
|
|
177
|
+
* and a shape that let them would invite a consumer to wonder whether they had.
|
|
178
|
+
*/
|
|
179
|
+
export declare const readerSignalBatchSchema: z.ZodObject<{
|
|
180
|
+
treeId: z.ZodBranded<z.ZodString, "TreeId">;
|
|
181
|
+
revision: z.ZodNumber;
|
|
182
|
+
sentAt: z.ZodNumber;
|
|
183
|
+
/**
|
|
184
|
+
* Which page view these signals came from, when the sender minted one.
|
|
185
|
+
*
|
|
186
|
+
* Optional because correlation is a capability rather than a requirement: a
|
|
187
|
+
* batch synthesised on a server, replayed from a fixture, or sent by a host
|
|
188
|
+
* that wants totals and no funnel has nothing to correlate, and refusing it
|
|
189
|
+
* would make the funnel mandatory rather than available. Rollup counts the
|
|
190
|
+
* batches it could not correlate instead of quietly treating each as its own
|
|
191
|
+
* view, which would inflate every funnel denominator.
|
|
192
|
+
*/
|
|
193
|
+
view: z.ZodOptional<z.ZodBranded<z.ZodString, "ViewKey">>;
|
|
194
|
+
signals: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
|
|
195
|
+
at: z.ZodNumber;
|
|
196
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
197
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
198
|
+
kind: z.ZodLiteral<"viewed">;
|
|
199
|
+
}, "strict", z.ZodTypeAny, {
|
|
200
|
+
at: number;
|
|
201
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
202
|
+
kind: "viewed";
|
|
203
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
204
|
+
}, {
|
|
205
|
+
at: number;
|
|
206
|
+
type: string;
|
|
207
|
+
kind: "viewed";
|
|
208
|
+
nodeId: string;
|
|
209
|
+
}>, z.ZodObject<{
|
|
210
|
+
ms: z.ZodNumber;
|
|
211
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
212
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
213
|
+
kind: z.ZodLiteral<"dwelled">;
|
|
214
|
+
}, "strict", z.ZodTypeAny, {
|
|
215
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
216
|
+
kind: "dwelled";
|
|
217
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
218
|
+
ms: number;
|
|
219
|
+
}, {
|
|
220
|
+
type: string;
|
|
221
|
+
kind: "dwelled";
|
|
222
|
+
nodeId: string;
|
|
223
|
+
ms: number;
|
|
224
|
+
}>, z.ZodObject<{
|
|
225
|
+
at: z.ZodNumber;
|
|
226
|
+
within: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
|
|
227
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
228
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
229
|
+
}, "strict", z.ZodTypeAny, {
|
|
230
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
231
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
232
|
+
}, {
|
|
233
|
+
type: string;
|
|
234
|
+
nodeId: string;
|
|
235
|
+
}>, "many">>>;
|
|
236
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
237
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
238
|
+
kind: z.ZodLiteral<"activated">;
|
|
239
|
+
}, "strict", z.ZodTypeAny, {
|
|
240
|
+
at: number;
|
|
241
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
242
|
+
kind: "activated";
|
|
243
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
244
|
+
within?: readonly {
|
|
245
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
246
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
247
|
+
}[] | undefined;
|
|
248
|
+
}, {
|
|
249
|
+
at: number;
|
|
250
|
+
type: string;
|
|
251
|
+
kind: "activated";
|
|
252
|
+
nodeId: string;
|
|
253
|
+
within?: readonly {
|
|
254
|
+
type: string;
|
|
255
|
+
nodeId: string;
|
|
256
|
+
}[] | undefined;
|
|
257
|
+
}>, z.ZodObject<{
|
|
258
|
+
open: z.ZodBoolean;
|
|
259
|
+
at: z.ZodNumber;
|
|
260
|
+
within: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
|
|
261
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
262
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
263
|
+
}, "strict", z.ZodTypeAny, {
|
|
264
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
265
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
266
|
+
}, {
|
|
267
|
+
type: string;
|
|
268
|
+
nodeId: string;
|
|
269
|
+
}>, "many">>>;
|
|
270
|
+
nodeId: z.ZodBranded<z.ZodString, "NodeId">;
|
|
271
|
+
type: z.ZodBranded<z.ZodString, "PrimitiveType">;
|
|
272
|
+
kind: z.ZodLiteral<"disclosed">;
|
|
273
|
+
}, "strict", z.ZodTypeAny, {
|
|
274
|
+
at: number;
|
|
275
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
276
|
+
kind: "disclosed";
|
|
277
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
278
|
+
open: boolean;
|
|
279
|
+
within?: readonly {
|
|
280
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
281
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
282
|
+
}[] | undefined;
|
|
283
|
+
}, {
|
|
284
|
+
at: number;
|
|
285
|
+
type: string;
|
|
286
|
+
kind: "disclosed";
|
|
287
|
+
nodeId: string;
|
|
288
|
+
open: boolean;
|
|
289
|
+
within?: readonly {
|
|
290
|
+
type: string;
|
|
291
|
+
nodeId: string;
|
|
292
|
+
}[] | undefined;
|
|
293
|
+
}>]>, "many">;
|
|
294
|
+
}, "strict", z.ZodTypeAny, {
|
|
295
|
+
treeId: string & z.BRAND<"TreeId">;
|
|
296
|
+
revision: number;
|
|
297
|
+
sentAt: number;
|
|
298
|
+
signals: ({
|
|
299
|
+
at: number;
|
|
300
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
301
|
+
kind: "viewed";
|
|
302
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
303
|
+
} | {
|
|
304
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
305
|
+
kind: "dwelled";
|
|
306
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
307
|
+
ms: number;
|
|
308
|
+
} | {
|
|
309
|
+
at: number;
|
|
310
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
311
|
+
kind: "activated";
|
|
312
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
313
|
+
within?: readonly {
|
|
314
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
315
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
316
|
+
}[] | undefined;
|
|
317
|
+
} | {
|
|
318
|
+
at: number;
|
|
319
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
320
|
+
kind: "disclosed";
|
|
321
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
322
|
+
open: boolean;
|
|
323
|
+
within?: readonly {
|
|
324
|
+
type: string & z.BRAND<"PrimitiveType">;
|
|
325
|
+
nodeId: string & z.BRAND<"NodeId">;
|
|
326
|
+
}[] | undefined;
|
|
327
|
+
})[];
|
|
328
|
+
view?: (string & z.BRAND<"ViewKey">) | undefined;
|
|
329
|
+
}, {
|
|
330
|
+
treeId: string;
|
|
331
|
+
revision: number;
|
|
332
|
+
sentAt: number;
|
|
333
|
+
signals: ({
|
|
334
|
+
at: number;
|
|
335
|
+
type: string;
|
|
336
|
+
kind: "viewed";
|
|
337
|
+
nodeId: string;
|
|
338
|
+
} | {
|
|
339
|
+
type: string;
|
|
340
|
+
kind: "dwelled";
|
|
341
|
+
nodeId: string;
|
|
342
|
+
ms: number;
|
|
343
|
+
} | {
|
|
344
|
+
at: number;
|
|
345
|
+
type: string;
|
|
346
|
+
kind: "activated";
|
|
347
|
+
nodeId: string;
|
|
348
|
+
within?: readonly {
|
|
349
|
+
type: string;
|
|
350
|
+
nodeId: string;
|
|
351
|
+
}[] | undefined;
|
|
352
|
+
} | {
|
|
353
|
+
at: number;
|
|
354
|
+
type: string;
|
|
355
|
+
kind: "disclosed";
|
|
356
|
+
nodeId: string;
|
|
357
|
+
open: boolean;
|
|
358
|
+
within?: readonly {
|
|
359
|
+
type: string;
|
|
360
|
+
nodeId: string;
|
|
361
|
+
}[] | undefined;
|
|
362
|
+
})[];
|
|
363
|
+
view?: string | undefined;
|
|
364
|
+
}>;
|
|
365
|
+
export type ReaderSignalBatch = z.infer<typeof readerSignalBatchSchema>;
|
|
366
|
+
export type ReaderSignalParseError = {
|
|
367
|
+
readonly code: "invalid-batch";
|
|
368
|
+
readonly issues: readonly {
|
|
369
|
+
readonly path: string;
|
|
370
|
+
readonly message: string;
|
|
371
|
+
}[];
|
|
372
|
+
};
|
|
373
|
+
/**
|
|
374
|
+
* Read a batch that arrived from somewhere untrusted — a request body, a queue.
|
|
375
|
+
*
|
|
376
|
+
* A browser is not a trusted author, so anything that receives batches parses
|
|
377
|
+
* them here rather than trusting the shape. Invalid input is a value, never a
|
|
378
|
+
* throw.
|
|
379
|
+
*/
|
|
380
|
+
export declare const parseReaderSignalBatch: (input: unknown) => Result<ReaderSignalBatch, ReaderSignalParseError>;
|
|
381
|
+
//# sourceMappingURL=signal.d.ts.map
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { nodeIdSchema, treeIdSchema } from "../ids.js";
|
|
3
|
+
import { primitiveTypeSchema } from "../primitive-type.js";
|
|
4
|
+
import { err, ok } from "../result.js";
|
|
5
|
+
import { READER_SIGNAL_KINDS } from "./kinds.js";
|
|
6
|
+
import { viewKeyPattern } from "./view.js";
|
|
7
|
+
/**
|
|
8
|
+
* What a published page may say about how it is being read.
|
|
9
|
+
*
|
|
10
|
+
* A reader signal is an observation about one node of one revision of one tree:
|
|
11
|
+
* it came into view, it stayed there this long, a reader activated a target in
|
|
12
|
+
* it, a reader opened or closed it. Nothing more, and deliberately so.
|
|
13
|
+
*
|
|
14
|
+
* **The vocabulary is closed.** Four kinds, for the same reason the operations on
|
|
15
|
+
* a tree are four and the schemes a URL may use are a list (0053): an adaptation
|
|
16
|
+
* is proposed from these, and a stream that may carry anything is a stream
|
|
17
|
+
* nothing can reason about. A kind is added here or it does not exist.
|
|
18
|
+
*
|
|
19
|
+
* **A signal carries no content.** No text a node shows, no URL a link goes to,
|
|
20
|
+
* no value a reader typed, nothing that identifies the reader. The tree already
|
|
21
|
+
* holds the content at the revision the signal names, and a record of what a
|
|
22
|
+
* person read is a record of that person — the rule telemetry already keeps for
|
|
23
|
+
* utterances (0023).
|
|
24
|
+
*
|
|
25
|
+
* **The revision is on every batch.** A signal about "the fourth section" means
|
|
26
|
+
* nothing once a proposal has moved it; a signal about node `n_42` at revision 3
|
|
27
|
+
* means exactly one thing forever (0136).
|
|
28
|
+
*/
|
|
29
|
+
export { DELEGATED_READER_SIGNAL_KINDS, READER_SIGNAL_KINDS } from "./kinds.js";
|
|
30
|
+
export const readerSignalKindSchema = z.enum(READER_SIGNAL_KINDS);
|
|
31
|
+
const instantSchema = z.number().int().nonnegative();
|
|
32
|
+
/**
|
|
33
|
+
* The key that says two batches came from the same page view, and says nothing
|
|
34
|
+
* else (0146).
|
|
35
|
+
*
|
|
36
|
+
* Branded like an id, but deliberately not one: it is minted by a browser
|
|
37
|
+
* rather than an id factory, it is not stable, nothing may be addressed by it,
|
|
38
|
+
* and it is dropped when the raw window expires. `view.ts` holds the pattern
|
|
39
|
+
* and the minting, because the broadcaster needs both and cannot load this
|
|
40
|
+
* module.
|
|
41
|
+
*/
|
|
42
|
+
export const viewKeySchema = z.string().regex(viewKeyPattern).brand();
|
|
43
|
+
const addressSchema = {
|
|
44
|
+
nodeId: nodeIdSchema,
|
|
45
|
+
type: primitiveTypeSchema,
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* One addressed node, as a signal names it.
|
|
49
|
+
*
|
|
50
|
+
* The same pair `addressSchema` spreads, as a schema of its own, because an
|
|
51
|
+
* ancestry is a list of them.
|
|
52
|
+
*/
|
|
53
|
+
export const signalAddressSchema = z.object(addressSchema).strict();
|
|
54
|
+
/**
|
|
55
|
+
* The addressed nodes a delegated signal happened inside, nearest first.
|
|
56
|
+
*
|
|
57
|
+
* A reader presses a button, and the button is an addressed node — so the node
|
|
58
|
+
* an `activated` is filed against is the control, never the band the control is
|
|
59
|
+
* in. Without this a deployment can report *which button was pressed* and can
|
|
60
|
+
* never report *how many readers used something in the pricing section*, because
|
|
61
|
+
* no signal a browser sends carries the section.
|
|
62
|
+
*
|
|
63
|
+
* **It is ancestry, not content.** Node ids and primitive types, which the tree
|
|
64
|
+
* at this revision already holds. A signal still says nothing about the reader
|
|
65
|
+
* and nothing about what the page shows.
|
|
66
|
+
*
|
|
67
|
+
* **Optional, and absent is not empty.** A batch synthesised on a server, one
|
|
68
|
+
* replayed from a fixture, and one from a sender that was asked not to walk all
|
|
69
|
+
* have nothing to say here; a signal against a node at the root of the page has
|
|
70
|
+
* an empty ancestry and says so. A consumer that treats the two the same is
|
|
71
|
+
* treating *we did not look* as *there was nothing above it*.
|
|
72
|
+
*/
|
|
73
|
+
const withinSchema = z.array(signalAddressSchema).readonly();
|
|
74
|
+
/**
|
|
75
|
+
* The four kinds.
|
|
76
|
+
*
|
|
77
|
+
* `viewed` fires once per node for the life of the page. `dwelled` is time on
|
|
78
|
+
* screen accumulated since the previous batch, so summing a node's `dwelled` over
|
|
79
|
+
* every batch is its total. `activated` is a reader using a link, button or field
|
|
80
|
+
* inside the node — the node named is the nearest addressed one, which in the
|
|
81
|
+
* starter library is usually the control itself. `disclosed` is a region opened
|
|
82
|
+
* or closed.
|
|
83
|
+
*
|
|
84
|
+
* Those last two are `DELEGATED_READER_SIGNAL_KINDS`: what a reader aimed at is
|
|
85
|
+
* a control, and the region it sits in is a question nothing else can answer
|
|
86
|
+
* afterwards, so they carry `within` and the other two do not.
|
|
87
|
+
*/
|
|
88
|
+
export const readerSignalSchema = z.discriminatedUnion("kind", [
|
|
89
|
+
z.object({ kind: z.literal("viewed"), ...addressSchema, at: instantSchema }).strict(),
|
|
90
|
+
z.object({ kind: z.literal("dwelled"), ...addressSchema, ms: z.number().int().positive() }).strict(),
|
|
91
|
+
z
|
|
92
|
+
.object({ kind: z.literal("activated"), ...addressSchema, at: instantSchema, within: withinSchema.optional() })
|
|
93
|
+
.strict(),
|
|
94
|
+
z
|
|
95
|
+
.object({
|
|
96
|
+
kind: z.literal("disclosed"),
|
|
97
|
+
...addressSchema,
|
|
98
|
+
open: z.boolean(),
|
|
99
|
+
at: instantSchema,
|
|
100
|
+
within: withinSchema.optional(),
|
|
101
|
+
})
|
|
102
|
+
.strict(),
|
|
103
|
+
]);
|
|
104
|
+
/**
|
|
105
|
+
* One delivery: the signals a page gathered since the last one, all about the
|
|
106
|
+
* same tree at the same revision.
|
|
107
|
+
*
|
|
108
|
+
* The tree and revision sit on the batch rather than on each signal because a
|
|
109
|
+
* rendered page is one revision of one tree — they cannot differ inside a batch,
|
|
110
|
+
* and a shape that let them would invite a consumer to wonder whether they had.
|
|
111
|
+
*/
|
|
112
|
+
export const readerSignalBatchSchema = z
|
|
113
|
+
.object({
|
|
114
|
+
treeId: treeIdSchema,
|
|
115
|
+
revision: z.number().int().nonnegative(),
|
|
116
|
+
sentAt: instantSchema,
|
|
117
|
+
/**
|
|
118
|
+
* Which page view these signals came from, when the sender minted one.
|
|
119
|
+
*
|
|
120
|
+
* Optional because correlation is a capability rather than a requirement: a
|
|
121
|
+
* batch synthesised on a server, replayed from a fixture, or sent by a host
|
|
122
|
+
* that wants totals and no funnel has nothing to correlate, and refusing it
|
|
123
|
+
* would make the funnel mandatory rather than available. Rollup counts the
|
|
124
|
+
* batches it could not correlate instead of quietly treating each as its own
|
|
125
|
+
* view, which would inflate every funnel denominator.
|
|
126
|
+
*/
|
|
127
|
+
view: viewKeySchema.optional(),
|
|
128
|
+
signals: z.array(readerSignalSchema).min(1),
|
|
129
|
+
})
|
|
130
|
+
.strict();
|
|
131
|
+
/**
|
|
132
|
+
* Read a batch that arrived from somewhere untrusted — a request body, a queue.
|
|
133
|
+
*
|
|
134
|
+
* A browser is not a trusted author, so anything that receives batches parses
|
|
135
|
+
* them here rather than trusting the shape. Invalid input is a value, never a
|
|
136
|
+
* throw.
|
|
137
|
+
*/
|
|
138
|
+
export const parseReaderSignalBatch = (input) => {
|
|
139
|
+
const parsed = readerSignalBatchSchema.safeParse(input);
|
|
140
|
+
return parsed.success
|
|
141
|
+
? ok(parsed.data)
|
|
142
|
+
: err({
|
|
143
|
+
code: "invalid-batch",
|
|
144
|
+
issues: parsed.error.issues.map((issue) => ({
|
|
145
|
+
path: issue.path.join("."),
|
|
146
|
+
message: issue.message,
|
|
147
|
+
})),
|
|
148
|
+
});
|
|
149
|
+
};
|
|
150
|
+
//# sourceMappingURL=signal.js.map
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import type { TreeId } from "../ids.js";
|
|
2
|
+
import type { Result } from "../result.js";
|
|
3
|
+
import type { FunnelAnswer, ReaderTally } from "./rollup.js";
|
|
4
|
+
import type { ReaderSignalStoreError } from "./journal.js";
|
|
5
|
+
/**
|
|
6
|
+
* Where the counters live once the batches they came from are gone.
|
|
7
|
+
*
|
|
8
|
+
* This is the durable half. The portal reads it, retention never touches it,
|
|
9
|
+
* and nothing in it can be traced to a reader: a tally is a node, a revision
|
|
10
|
+
* and six numbers.
|
|
11
|
+
*
|
|
12
|
+
* **Applying a rollup is additive, not a replacement.** Rollup runs over a
|
|
13
|
+
* window of the buffer and is run again over the next window, so what it
|
|
14
|
+
* produces is *what this window added* rather than *what is true so far*. A
|
|
15
|
+
* store that overwrote would silently discard every window but the last, and
|
|
16
|
+
* the symptom — counters that look plausible and only ever describe the last
|
|
17
|
+
* few minutes — is the kind nobody notices.
|
|
18
|
+
*
|
|
19
|
+
* **Except the view counts, which is the one place this is lossy and the
|
|
20
|
+
* reason it is written down here (0147).** `views` and `reached` count *distinct*
|
|
21
|
+
* views, and distinctness cannot be added up: a reader whose page view spans
|
|
22
|
+
* two windows is one view in each and two after the sum. The error is bounded
|
|
23
|
+
* by how many views straddle a window boundary, it is always an over-count, and
|
|
24
|
+
* the alternative is keeping view keys in durable storage — which is the thing
|
|
25
|
+
* 0146 refuses. A deployment that wants the bound small makes the rollup window
|
|
26
|
+
* long relative to a page view, which is the default.
|
|
27
|
+
*/
|
|
28
|
+
/** One node's line as the store keeps it, which is a tally plus when it last changed. */
|
|
29
|
+
export type StoredTally = ReaderTally & {
|
|
30
|
+
readonly updatedAt: string;
|
|
31
|
+
};
|
|
32
|
+
/** One funnel answer as the store keeps it. */
|
|
33
|
+
export type StoredFunnel = FunnelAnswer & {
|
|
34
|
+
readonly updatedAt: string;
|
|
35
|
+
};
|
|
36
|
+
export type TallyReadRequest = {
|
|
37
|
+
/** Absent reads every tree the handle can see, which is the scope rule (0020). */
|
|
38
|
+
readonly treeId?: TreeId;
|
|
39
|
+
/**
|
|
40
|
+
* Absent reads every revision.
|
|
41
|
+
*
|
|
42
|
+
* Almost every question the portal asks is about one revision or about two
|
|
43
|
+
* being compared, and *before versus after a change* is the second of those —
|
|
44
|
+
* so this is a filter rather than a requirement, and a caller comparing
|
|
45
|
+
* revisions reads them all and groups.
|
|
46
|
+
*/
|
|
47
|
+
readonly revision?: number;
|
|
48
|
+
};
|
|
49
|
+
/**
|
|
50
|
+
* Counters are not paged.
|
|
51
|
+
*
|
|
52
|
+
* A page of a log is unbounded because a log only grows; tallies are bounded by
|
|
53
|
+
* the nodes of the revisions a deployment has, which is the size of its trees.
|
|
54
|
+
* Paging them would be a cursor every caller has to carry for a result that
|
|
55
|
+
* fits in a response.
|
|
56
|
+
*/
|
|
57
|
+
export interface ReaderTallyStore {
|
|
58
|
+
/**
|
|
59
|
+
* Add a rollup's counters to what is already there, creating rows that do not
|
|
60
|
+
* exist yet. Atomic over the whole rollup where the backend can be: a partly
|
|
61
|
+
* applied window is counters that disagree with each other.
|
|
62
|
+
*/
|
|
63
|
+
readonly apply: (rollup: {
|
|
64
|
+
readonly tallies: readonly ReaderTally[];
|
|
65
|
+
readonly funnels: readonly FunnelAnswer[];
|
|
66
|
+
}, at: string) => Promise<Result<void, ReaderSignalStoreError>>;
|
|
67
|
+
readonly tallies: (request?: TallyReadRequest) => Promise<Result<readonly StoredTally[], ReaderSignalStoreError>>;
|
|
68
|
+
readonly funnels: (request?: TallyReadRequest) => Promise<Result<readonly StoredFunnel[], ReaderSignalStoreError>>;
|
|
69
|
+
}
|
|
70
|
+
//# sourceMappingURL=tally.d.ts.map
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import type { ViewKey } from "./signal.js";
|
|
2
|
+
/**
|
|
3
|
+
* The one value in the reader-signal seam that correlates anything.
|
|
4
|
+
*
|
|
5
|
+
* A view key is minted in the browser when a broadcast starts, rides every
|
|
6
|
+
* batch of that one page view, and is never seen again. It exists so a funnel
|
|
7
|
+
* can be answered — *of the views that reached the pricing band, how many
|
|
8
|
+
* pressed the button* — which per-node totals cannot answer and which is half
|
|
9
|
+
* of what the portal is for ([0146](../../decisions/0146-a-reader-signal-stays-anonymous-and-a-funnel-is-correlated-inside-one-page-view.md)).
|
|
10
|
+
*
|
|
11
|
+
* Everything else about it is a refusal. It is not a cookie and is not written
|
|
12
|
+
* to storage of any kind, so it does not survive a reload. It is not derived
|
|
13
|
+
* from the reader, their device, their address or their clock — it is random
|
|
14
|
+
* bytes and nothing else. It does not leave the aggregation step: rollup reads
|
|
15
|
+
* it and the counters it produces do not carry it, so it expires with the raw
|
|
16
|
+
* window.
|
|
17
|
+
*
|
|
18
|
+
* **The shape is strict for a reason that is not tidiness.** A free-form string
|
|
19
|
+
* here is an identity backdoor: a host wanting a visitor id could put one in
|
|
20
|
+
* this field and everything downstream would keep working. Thirty-two hex
|
|
21
|
+
* characters of nothing hold no room for a hash of an address, an account id,
|
|
22
|
+
* or a user agent, and a batch carrying one is refused at the parser rather
|
|
23
|
+
* than stored and noticed later.
|
|
24
|
+
*
|
|
25
|
+
* This module is loaded by the broadcaster, so it imports no package and
|
|
26
|
+
* touches no schema (0136). The schema built from the constants below lives in
|
|
27
|
+
* `signal.ts`, which a browser never loads.
|
|
28
|
+
*/
|
|
29
|
+
/**
|
|
30
|
+
* 128 bits, the same width a UUID spends on randomness.
|
|
31
|
+
*
|
|
32
|
+
* The number that matters is not the collision probability against all views
|
|
33
|
+
* ever, but against the views inside one raw window on one deployment — the
|
|
34
|
+
* only span in which two keys are ever compared. At 128 bits that is
|
|
35
|
+
* unreachable, and the field costs 32 bytes on a batch that already carries
|
|
36
|
+
* several signals.
|
|
37
|
+
*/
|
|
38
|
+
export declare const VIEW_KEY_BYTES = 16;
|
|
39
|
+
export declare const VIEW_KEY_LENGTH: number;
|
|
40
|
+
export declare const viewKeyPattern: RegExp;
|
|
41
|
+
/**
|
|
42
|
+
* Where the randomness comes from. A parameter so a test can mint a key it can
|
|
43
|
+
* name, and for no other reason — a host has no business supplying this.
|
|
44
|
+
*/
|
|
45
|
+
export type RandomBytes = (count: number) => Uint8Array;
|
|
46
|
+
/**
|
|
47
|
+
* A fresh view key. Called once per broadcast, never per batch — the whole
|
|
48
|
+
* point is that the batches of one page view agree.
|
|
49
|
+
*/
|
|
50
|
+
export declare const mintViewKey: (random?: RandomBytes) => ViewKey;
|
|
51
|
+
//# sourceMappingURL=view.d.ts.map
|