@jam-overture/loom 0.2.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.
Files changed (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,190 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { NodeId, TreeId } from "../ids.js";
3
+ import type { PrimitiveType } from "../primitive-type.js";
4
+ import type { PrimitiveRole } from "../role.js";
5
+ import type { NodeCopy } from "../sdk/copy.js";
6
+ import type { LoomTree } from "../tree/tree.js";
7
+ import { type ActedCounts, type ActedKind, type StoredActed } from "./acted.js";
8
+ import type { ArrivalRange } from "./arrivals.js";
9
+ import type { PartDeclarations } from "./parts.js";
10
+ /**
11
+ * One part of the page, what readers did to it, and what they did inside it.
12
+ *
13
+ * The three facts about where it sits are here rather than left to a caller
14
+ * because they are what the answer means: *forty presses inside this* is a
15
+ * sentence about a region of a page, and a list that did not say which regions
16
+ * contain which others would be forty presses counted as many times as a
17
+ * caller added rows together.
18
+ */
19
+ export type InsidePart = {
20
+ readonly nodeId: NodeId;
21
+ readonly type: PrimitiveType;
22
+ /** What part it plays (0114), or `null` where its type declared none. */
23
+ readonly role: PrimitiveRole | null;
24
+ /** Depth in the tree, counting every node; 0 at the root. */
25
+ readonly depth: number;
26
+ /**
27
+ * The nearest **addressed** ancestor, which is what `within` names (0167),
28
+ * and `null` at the outermost part.
29
+ *
30
+ * Not the tree parent. A slot is a node with children and is never a part —
31
+ * no signal can name one, because only an element carries the identity
32
+ * attributes a broadcaster reads — so the part immediately containing an
33
+ * element is the nearest *element* above it, with any slots between them
34
+ * passed through. A reading keyed on the tree parent would hang a band off a
35
+ * node that appears nowhere in its own list.
36
+ */
37
+ readonly withinId: NodeId | null;
38
+ /** What readers did to this part itself, in the range. */
39
+ readonly own: ActedCounts;
40
+ /**
41
+ * What readers did to this part and to every part inside it, in the range.
42
+ *
43
+ * Each action is in exactly one part's `own` and in the `inside` of each of
44
+ * that part's ancestors, so this adds **down** a tree and never across one:
45
+ * two siblings' `inside` may be added, a part's and its child's may not.
46
+ */
47
+ readonly inside: ActedCounts;
48
+ /** Addressed nodes in its subtree, itself included — so 1 for a part with no parts in it. */
49
+ readonly parts: number;
50
+ /**
51
+ * The words this part says itself: its declared copy props, and the text
52
+ * handed to it directly or through a slot.
53
+ *
54
+ * Its own, never its subtree's, exactly as `PartReading.copy` is and by the
55
+ * same function — so *a reader pressed `Get started`* is a sentence a surface
56
+ * can write, and a caller adding two parts' words together reads no headline
57
+ * twice.
58
+ */
59
+ readonly copy: NodeCopy;
60
+ };
61
+ /**
62
+ * What a range of the hourly counter says about the shape of one revision of
63
+ * one page.
64
+ */
65
+ export type InsideReading = {
66
+ readonly treeId: TreeId;
67
+ readonly revision: number;
68
+ readonly range: ArrivalRange;
69
+ /** Every addressed node, in reading order, so a row is always preceded by the row it is inside. */
70
+ readonly parts: readonly InsidePart[];
71
+ /**
72
+ * Everything readers did on this page in the range.
73
+ *
74
+ * The sum of every part's `own`. A tree's root is always an element
75
+ * (`tree.ts`), so this is also the root's own `inside` — and it is computed
76
+ * the other way deliberately: the two routes to one number share no
77
+ * arithmetic, so a test that holds them equal is a check on the accumulation
78
+ * that the accumulation cannot pass by being consistently wrong.
79
+ */
80
+ readonly total: ActedCounts;
81
+ /**
82
+ * Every audience whose rows were summed into this reading.
83
+ *
84
+ * A census rather than a refusal (0297): the figures here are occurrences, so
85
+ * two forms of a page add honestly, and what a caller needs is to know that
86
+ * two were added. More than one member means this answer is about a page
87
+ * served in two forms; narrow the read if that is not what was wanted.
88
+ */
89
+ readonly audiences: readonly AudienceId[];
90
+ /** Rows summed into the reading. */
91
+ readonly counted: number;
92
+ /**
93
+ * Rows filed under another tree or another revision, and ignored.
94
+ *
95
+ * `parts.ts`' reason, sharpened by the ancestry: a node's place in the page
96
+ * is a fact about one revision, so a row from another one would be credited
97
+ * to whatever happens to contain that node now.
98
+ */
99
+ readonly foreign: number;
100
+ /**
101
+ * Rows of this tree and revision whose hour falls outside the range, and
102
+ * ignored.
103
+ *
104
+ * Ignored rather than refused, because a wider read is the ordinary way a
105
+ * caller gets a range and the period before it from one call
106
+ * (`actedSeriesOf`). Counted separately from `foreign` so *you passed last
107
+ * month's rows* and *you passed another page's* are two different sentences.
108
+ */
109
+ readonly outside: number;
110
+ /**
111
+ * Nodes named by a row this revision does not contain.
112
+ *
113
+ * The alarm `parts.ts` carries, and it matters more here: an orphaned row is
114
+ * an action that happened on the page and is in **no** part's `inside`, so
115
+ * the totals under-report by exactly what this names. A non-empty list says
116
+ * the tree and the rows do not belong together.
117
+ */
118
+ readonly orphaned: readonly NodeId[];
119
+ /**
120
+ * The first hour this scope ever counted an action in, carried through from
121
+ * the store.
122
+ *
123
+ * Absent means nothing has ever been counted here, which is a different
124
+ * sentence from *nobody did anything inside anything in the range you asked
125
+ * about* (0309, 0347).
126
+ */
127
+ readonly begins?: number;
128
+ };
129
+ /**
130
+ * Join a range of the hourly counter to the tree and registry it was filed
131
+ * against, and read it as the page's own shape.
132
+ *
133
+ * **One read in, one reading out, and that is a guard rather than an
134
+ * ergonomic.** `parts.ts` can refuse a tally handed in twice because a tally is
135
+ * one row per part; an hour's counter legitimately has many rows per part, so a
136
+ * duplicate here is invisible and would inflate every ancestor of it. Taking a
137
+ * single {@link StoredActed} is what makes *a caller passed the same rows
138
+ * twice* unspellable instead of undetectable (0158).
139
+ *
140
+ * Linear in the parts and in the rows: the rows are bucketed once, the parts are
141
+ * walked once to find each one's nearest addressed ancestor, and the subtree
142
+ * totals are accumulated in one pass back up the same list. The reading the
143
+ * ledger's bound exists for (rule 4) is not allowed to walk a part's ancestors
144
+ * per part.
145
+ */
146
+ export declare const insideReadingOf: (tree: LoomTree, stored: StoredActed, declarations: PartDeclarations, range: ArrivalRange) => InsideReading;
147
+ /**
148
+ * The parts readers acted on most in the range, most first.
149
+ *
150
+ * **By what readers did to the part itself**, never by what they did inside it:
151
+ * ordering by `inside` ranks every page by its outermost part, because an
152
+ * ancestor's total is never below its descendant's. The question this answers is
153
+ * *what did readers press*, and the answer to that is a button.
154
+ *
155
+ * One kind, for `actedSeriesOf`' reason — a list with presses and sends added
156
+ * together is a list of two different things — and parts nobody did anything to
157
+ * are absent rather than listed as noughts: the universe of parts that *could*
158
+ * have been pressed is not something a tree can say today, so a list padded with
159
+ * every heading on the page would read as a claim this reading cannot make.
160
+ * {@link InsideReading.parts} holds the whole page for a caller that wants it.
161
+ *
162
+ * Ties keep reading order, so a page with ten parts at one press each is drawn
163
+ * in the order it is written rather than in the order a sort happened to leave
164
+ * them.
165
+ */
166
+ export declare const actedMostIn: (reading: InsideReading, kind: ActedKind, limit?: number) => readonly InsidePart[];
167
+ /**
168
+ * The share of everything readers did on the page, in one kind, that happened
169
+ * inside one part — between 0 and 1.
170
+ *
171
+ * *Sixty-two per cent of the presses on this page were in the pricing band* is
172
+ * the sentence, and it is exact rather than estimated: the numerator and the
173
+ * denominator are counts of the same occurrences over the same rows, and each
174
+ * occurrence is in both or in neither.
175
+ *
176
+ * `null` where readers did nothing of that kind on the page at all. A nought
177
+ * there would read as *this part gets none of them*, which is a claim about the
178
+ * part, and what is true is that there are none to share out.
179
+ */
180
+ export declare const insideShareIn: (reading: InsideReading, part: InsidePart, kind: ActedKind) => number | null;
181
+ /**
182
+ * What readers did inside a part but not to the part itself.
183
+ *
184
+ * The figure that says whether a band is a thing readers use or a thing that
185
+ * holds things readers use — and the one a surface would otherwise get by
186
+ * subtracting two numbers it was handed, which is the subtraction that is wrong
187
+ * if either of them is the other kind's.
188
+ */
189
+ export declare const beneathOf: (part: InsidePart, kind: ActedKind) => number;
190
+ //# sourceMappingURL=inside.d.ts.map
@@ -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