@drupflare/spool 0.3.0 → 1.0.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 (206) hide show
  1. package/README.md +279 -1607
  2. package/dist/angular/index.d.ts +13 -0
  3. package/dist/angular/index.js +25 -0
  4. package/dist/angular/pages.d.ts +28 -0
  5. package/dist/angular/pages.js +85 -0
  6. package/dist/cdn/client.js +1 -1
  7. package/dist/cdn/location.d.ts +6 -0
  8. package/dist/cdn/location.js +8 -0
  9. package/dist/cdn/manifest.json +7 -7
  10. package/dist/cdn/spool-sw.js +1 -1
  11. package/dist/client/bootstrap.d.ts +57 -0
  12. package/dist/client/bootstrap.js +307 -0
  13. package/dist/client/contact.d.ts +24 -0
  14. package/dist/client/contact.js +66 -0
  15. package/dist/client/declared.d.ts +23 -0
  16. package/dist/client/declared.js +68 -0
  17. package/dist/client/entry.js +123 -2
  18. package/dist/client/gate.d.ts +1 -0
  19. package/dist/client/gate.js +148 -0
  20. package/dist/client/index.d.ts +25 -0
  21. package/dist/client/index.js +1 -0
  22. package/dist/client/live.d.ts +66 -0
  23. package/dist/client/live.js +225 -0
  24. package/dist/client/navigate-entry.d.ts +1 -0
  25. package/dist/client/navigate-entry.js +4 -0
  26. package/dist/client/navigate.d.ts +54 -0
  27. package/dist/client/navigate.js +272 -0
  28. package/dist/client/persist.d.ts +2 -0
  29. package/dist/client/persist.js +9 -0
  30. package/dist/client/register.d.ts +34 -2
  31. package/dist/client/register.js +64 -7
  32. package/dist/express/index.d.ts +11 -0
  33. package/dist/express/index.js +209 -0
  34. package/dist/hono/index.d.ts +19 -0
  35. package/dist/hono/index.js +49 -0
  36. package/dist/next/index.d.ts +33 -0
  37. package/dist/next/index.js +41 -0
  38. package/dist/next/pages.d.ts +22 -0
  39. package/dist/next/pages.js +39 -0
  40. package/dist/node/listener.d.ts +3 -0
  41. package/dist/node/listener.js +57 -2
  42. package/dist/nuxt/index.d.ts +22 -0
  43. package/dist/nuxt/index.js +104 -0
  44. package/dist/nuxt/pages.d.ts +26 -0
  45. package/dist/nuxt/pages.js +48 -0
  46. package/dist/nuxt/runtime/index.d.ts +24 -0
  47. package/dist/nuxt/runtime/index.js +58 -0
  48. package/dist/plugins/coverage.d.ts +14 -0
  49. package/dist/plugins/coverage.js +27 -0
  50. package/dist/plugins/mode.d.ts +19 -0
  51. package/dist/plugins/mode.js +20 -0
  52. package/dist/plugins/path.d.ts +16 -0
  53. package/dist/plugins/path.js +139 -0
  54. package/dist/plugins/report.d.ts +22 -0
  55. package/dist/plugins/report.js +18 -0
  56. package/dist/plugins/routes.d.ts +38 -0
  57. package/dist/plugins/routes.js +52 -0
  58. package/dist/plugins/static.d.ts +42 -0
  59. package/dist/plugins/static.js +97 -0
  60. package/dist/protocol/bundle.d.ts +111 -0
  61. package/dist/protocol/bundle.js +428 -0
  62. package/dist/protocol/config.d.ts +80 -1
  63. package/dist/protocol/config.js +31 -1
  64. package/dist/protocol/dataset.d.ts +189 -0
  65. package/dist/protocol/dataset.js +212 -0
  66. package/dist/protocol/envelope.d.ts +34 -1
  67. package/dist/protocol/envelope.js +16 -1
  68. package/dist/protocol/errors.d.ts +1 -1
  69. package/dist/protocol/graph.d.ts +23 -4
  70. package/dist/protocol/graph.js +34 -3
  71. package/dist/protocol/index-rows.d.ts +22 -0
  72. package/dist/protocol/index-rows.js +53 -0
  73. package/dist/protocol/index.d.ts +5 -0
  74. package/dist/protocol/index.js +5 -0
  75. package/dist/protocol/normalise.d.ts +4 -4
  76. package/dist/protocol/normalise.js +9 -5
  77. package/dist/protocol/plan.d.ts +100 -0
  78. package/dist/protocol/plan.js +661 -0
  79. package/dist/protocol/provision.d.ts +46 -0
  80. package/dist/protocol/provision.js +38 -0
  81. package/dist/protocol/query.d.ts +66 -5
  82. package/dist/protocol/query.js +103 -4
  83. package/dist/protocol/ring.d.ts +58 -0
  84. package/dist/protocol/ring.js +6 -0
  85. package/dist/protocol/route.d.ts +63 -13
  86. package/dist/protocol/route.js +126 -6
  87. package/dist/protocol/tag.d.ts +22 -2
  88. package/dist/protocol/tag.js +25 -4
  89. package/dist/protocol/view.d.ts +2 -0
  90. package/dist/protocol/view.js +8 -2
  91. package/dist/protocol/views.d.ts +6 -0
  92. package/dist/protocol/views.js +15 -0
  93. package/dist/protocol/write.d.ts +234 -0
  94. package/dist/protocol/write.js +343 -0
  95. package/dist/proxy/eligible.d.ts +22 -1
  96. package/dist/proxy/eligible.js +62 -15
  97. package/dist/proxy/proxy.js +28 -18
  98. package/dist/react-router/index.d.ts +20 -0
  99. package/dist/react-router/index.js +60 -0
  100. package/dist/react-router/pages.d.ts +34 -0
  101. package/dist/react-router/pages.js +83 -0
  102. package/dist/report/dataset.d.ts +48 -0
  103. package/dist/report/dataset.js +93 -0
  104. package/dist/report/demand.d.ts +49 -0
  105. package/dist/report/demand.js +60 -0
  106. package/dist/report/derive.d.ts +285 -0
  107. package/dist/report/derive.js +676 -1
  108. package/dist/report/economics.d.ts +66 -1
  109. package/dist/report/economics.js +208 -1
  110. package/dist/report/headline.d.ts +158 -0
  111. package/dist/report/headline.js +473 -0
  112. package/dist/report/index.d.ts +4 -0
  113. package/dist/report/index.js +4 -0
  114. package/dist/report/inputs.d.ts +176 -0
  115. package/dist/report/inputs.js +248 -0
  116. package/dist/report/institution.d.ts +188 -1
  117. package/dist/report/institution.js +146 -0
  118. package/dist/report/loops.d.ts +73 -0
  119. package/dist/report/loops.js +101 -0
  120. package/dist/report/measurement.d.ts +1 -1
  121. package/dist/report/measurement.js +7 -1
  122. package/dist/report/model.d.ts +2 -0
  123. package/dist/report/model.js +4 -0
  124. package/dist/report/thirdparty.d.ts +57 -0
  125. package/dist/report/thirdparty.js +111 -0
  126. package/dist/report/traffic.d.ts +8 -0
  127. package/dist/report/traffic.js +7 -0
  128. package/dist/report/trim.d.ts +56 -0
  129. package/dist/report/trim.js +83 -1
  130. package/dist/server/bundle.d.ts +55 -0
  131. package/dist/server/bundle.js +172 -0
  132. package/dist/server/dataset.d.ts +54 -0
  133. package/dist/server/dataset.js +355 -0
  134. package/dist/server/embedded.d.ts +7 -3
  135. package/dist/server/embedded.js +7 -3
  136. package/dist/server/index.d.ts +6 -0
  137. package/dist/server/index.js +6 -0
  138. package/dist/server/live-sockets.d.ts +54 -0
  139. package/dist/server/live-sockets.js +131 -0
  140. package/dist/server/live.d.ts +146 -0
  141. package/dist/server/live.js +228 -0
  142. package/dist/server/ring.d.ts +77 -0
  143. package/dist/server/ring.js +311 -0
  144. package/dist/server/spool.d.ts +158 -3
  145. package/dist/server/spool.js +578 -41
  146. package/dist/server/static.d.ts +42 -0
  147. package/dist/server/static.js +29 -0
  148. package/dist/server/stub.d.ts +43 -5
  149. package/dist/server/stub.js +126 -8
  150. package/dist/server/write.d.ts +49 -0
  151. package/dist/server/write.js +223 -0
  152. package/dist/stores/durable-object.d.ts +46 -0
  153. package/dist/stores/durable-object.js +114 -0
  154. package/dist/sw/analytics.d.ts +7 -1
  155. package/dist/sw/analytics.js +16 -2
  156. package/dist/sw/coverage.d.ts +6 -0
  157. package/dist/sw/coverage.js +34 -0
  158. package/dist/sw/dataset-sync.d.ts +76 -0
  159. package/dist/sw/dataset-sync.js +149 -0
  160. package/dist/sw/dataset.d.ts +91 -0
  161. package/dist/sw/dataset.js +318 -0
  162. package/dist/sw/family.d.ts +15 -0
  163. package/dist/sw/family.js +48 -0
  164. package/dist/sw/graph/index.d.ts +31 -1
  165. package/dist/sw/graph/index.js +57 -5
  166. package/dist/sw/graph/invalidate.d.ts +15 -3
  167. package/dist/sw/graph/invalidate.js +42 -4
  168. package/dist/sw/idb.d.ts +2 -0
  169. package/dist/sw/idb.js +80 -11
  170. package/dist/sw/index.d.ts +2 -0
  171. package/dist/sw/index.js +1 -0
  172. package/dist/sw/pack/store.d.ts +128 -0
  173. package/dist/sw/pack/store.js +737 -0
  174. package/dist/sw/partition.d.ts +6 -1
  175. package/dist/sw/partition.js +21 -2
  176. package/dist/sw/policy.d.ts +2 -0
  177. package/dist/sw/policy.js +11 -0
  178. package/dist/sw/principal-dataset.d.ts +64 -0
  179. package/dist/sw/principal-dataset.js +254 -0
  180. package/dist/sw/probe.d.ts +16 -0
  181. package/dist/sw/probe.js +25 -0
  182. package/dist/sw/render.d.ts +7 -2
  183. package/dist/sw/render.js +19 -5
  184. package/dist/sw/replica.d.ts +12 -3
  185. package/dist/sw/replica.js +40 -5
  186. package/dist/sw/router.d.ts +3 -2
  187. package/dist/sw/router.js +15 -2
  188. package/dist/sw/runtime.d.ts +90 -2
  189. package/dist/sw/runtime.js +857 -61
  190. package/dist/sw/scheduler.d.ts +6 -1
  191. package/dist/sw/scheduler.js +22 -5
  192. package/dist/sw/seal.d.ts +13 -0
  193. package/dist/sw/seal.js +13 -4
  194. package/dist/sw/static.d.ts +18 -0
  195. package/dist/sw/static.js +84 -1
  196. package/dist/sw/storage.d.ts +51 -1
  197. package/dist/sw/storage.js +33 -1
  198. package/dist/sw/write.d.ts +147 -0
  199. package/dist/sw/write.js +625 -0
  200. package/dist/version.d.ts +1 -1
  201. package/dist/version.js +1 -2
  202. package/dist/vite/index.d.ts +26 -0
  203. package/dist/vite/index.js +66 -0
  204. package/dist/vue/index.d.ts +36 -0
  205. package/dist/vue/index.js +53 -0
  206. package/package.json +65 -4
@@ -0,0 +1,473 @@
1
+ import { BOOTSTRAP_EXTRA_NO_WORKER, CF_FREE_REQUESTS_PER_DAY, paidRequestsUsd, requestsPerReadView, webkitStubPerReadView } from './economics.js';
2
+ import { DOCUMENT_BYTES } from './inputs.js';
3
+ /** engine classes the headline compares; WebKit under the default `workerMode: 'auto'` has no worker */
4
+ export const ENGINE_CLASSES = ['worker', 'webkit-auto', 'webkit-always', 'no-worker'];
5
+ /** what each engine class is, as the page words it */
6
+ export const ENGINE_CLASS_LABELS = {
7
+ worker: 'Chromium and Firefox, worker',
8
+ 'webkit-auto': 'WebKit, default (no worker)',
9
+ 'webkit-always': "WebKit, `workerMode: 'always'`",
10
+ 'no-worker': 'no worker'
11
+ };
12
+ /** the WebKit default registers no worker, so it is the no-worker class */
13
+ export const CLASS_OF_ENGINE_DEFAULT = {
14
+ worker: 'worker',
15
+ 'webkit-auto': 'no-worker',
16
+ 'webkit-always': 'webkit-always',
17
+ 'no-worker': 'no-worker'
18
+ };
19
+ /** share of a baseline that spool avoids; negative where spool sends more than the baseline */
20
+ export function avoidedShare(baseline, spool) {
21
+ if (!(baseline > 0))
22
+ throw new RangeError(`baseline must be positive, got ${baseline}`);
23
+ return (baseline - spool) / baseline;
24
+ }
25
+ /** baseline over spool; Infinity when spool sends nothing, below 1 when spool sends more */
26
+ export function multiplierOf(baseline, spool) {
27
+ if (!(baseline > 0))
28
+ throw new RangeError(`baseline must be positive, got ${baseline}`);
29
+ return spool === 0 ? Infinity : baseline / spool;
30
+ }
31
+ /**
32
+ * Requests per read view for a client with no worker. Each document navigation after the first
33
+ * reaches the origin (L1, `never` arm in the WebKit lane), so `lifetimes x e - 1` of them add to the
34
+ * bootstrap count. `e` is the workload's document navigations per lifetime.
35
+ */
36
+ export function noWorkerRequestsPerReadView(w) {
37
+ const extra = (w.lifetimes * w.webkitNavigations.value - 1) / (w.lifetimes * w.viewsPerLifetime);
38
+ return requestsPerReadView(w, BOOTSTRAP_EXTRA_NO_WORKER.value) + extra;
39
+ }
40
+ /** Worker requests per read view for an engine class; WebKit `auto` is the no-worker class */
41
+ export function requestsByClass(w, cls) {
42
+ switch (CLASS_OF_ENGINE_DEFAULT[cls]) {
43
+ case 'worker':
44
+ return requestsPerReadView(w);
45
+ case 'webkit-always':
46
+ return requestsPerReadView(w) + webkitStubPerReadView(w);
47
+ default:
48
+ return noWorkerRequestsPerReadView(w);
49
+ }
50
+ }
51
+ /** the best and the worst engine class for one workload, by requests per read view */
52
+ export function bestAndWorst(w, baseline) {
53
+ const rows = ENGINE_CLASSES.map((cls) => {
54
+ const requests = requestsByClass(w, cls);
55
+ return {
56
+ cls,
57
+ requests,
58
+ share: avoidedShare(baseline, requests),
59
+ multiplier: multiplierOf(baseline, requests)
60
+ };
61
+ });
62
+ const sorted = [...rows].sort((a, b) => a.requests - b.requests);
63
+ return {
64
+ best: sorted[0],
65
+ worst: sorted[sorted.length - 1],
66
+ reversed: rows.filter((r) => r.requests >= baseline).map((r) => r.cls)
67
+ };
68
+ }
69
+ /** monthly Worker requests and the paid-plan dollars for `views` read views at `requests` each */
70
+ export function paidMonth(views, requests) {
71
+ return { requests: views * requests, usd: paidRequestsUsd(views * requests) };
72
+ }
73
+ /** where a headline's counts come from; every headline row carries exactly one of these */
74
+ export const PROVENANCE = [
75
+ 'library 1.0.0, measured',
76
+ 'library 1.0.0 page runtime, no worker',
77
+ 'model over library counts (L3)',
78
+ 'review construction, not shipped',
79
+ 'bound, no count'
80
+ ];
81
+ /** provenances that move a row out of the headline sections into the not-shipped section */
82
+ export const NOT_SHIPPED = [
83
+ 'review construction, not shipped',
84
+ 'bound, no count'
85
+ ];
86
+ /** whether the spool arm of one finished pair was controlled by the worker (the reading's `controlled` field) */
87
+ export function spoolControlled(reading, engine, scenario) {
88
+ const row = rowsOf(reading).find((r) => r.arm === 'spool' && r.engine === engine && r.scenario === scenario);
89
+ if (!row)
90
+ throw new RangeError(`no spool arm for ${engine} ${scenario}`);
91
+ return row.controlled === true;
92
+ }
93
+ const LAYERS = new Set(['L0', 'L1', 'L2', 'L3']);
94
+ /** throws a RangeError naming every headline whose layer is missing or not one of L0 to L3 */
95
+ export function requireLayers(rows) {
96
+ const bad = rows.filter((r) => !LAYERS.has(r.layer)).map((r) => r.id);
97
+ if (bad.length)
98
+ throw new RangeError(`headline without a layer: ${bad.join(', ')}`);
99
+ return rows;
100
+ }
101
+ const rowsOf = (reading) => reading.rows;
102
+ const usable = (r) => !r.fatal && !(r.wrong && r.wrong > 0);
103
+ /** paths the demand site's spool arm requests, by role */
104
+ export const DEMAND_PATHS = {
105
+ boot: 'GET /.spool/1.0.0/boot/1.js',
106
+ stub: 'GET /spool-sw.js'
107
+ };
108
+ /** baseline and spool request counts for every scenario and engine where both arms finished (L1) */
109
+ export function demandCounts(reading) {
110
+ const rows = rowsOf(reading).filter(usable);
111
+ const out = [];
112
+ for (const spool of rows.filter((r) => r.arm === 'spool')) {
113
+ const base = rows.find((r) => r.arm === 'baseline' && r.engine === spool.engine && r.scenario === spool.scenario);
114
+ if (!base)
115
+ continue;
116
+ out.push({
117
+ scenario: spool.scenario,
118
+ engine: spool.engine,
119
+ views: spool.views,
120
+ baseline: base.requests,
121
+ spool: spool.requests
122
+ });
123
+ }
124
+ return out;
125
+ }
126
+ /** bytes of the baseline and spool arms for a scenario and engine (L1) */
127
+ export function demandBytes(reading, engine, scenario) {
128
+ const rows = rowsOf(reading).filter(usable);
129
+ const base = rows.find((r) => r.arm === 'baseline' && r.engine === engine && r.scenario === scenario);
130
+ const spool = rows.find((r) => r.arm === 'spool' && r.engine === engine && r.scenario === scenario);
131
+ if (!base || !spool)
132
+ throw new RangeError(`no finished ${engine} arms for ${scenario}`);
133
+ return { baseline: base.bytes, spool: spool.bytes };
134
+ }
135
+ /** Worker-invocation equivalents: every request but the boot script and the stub, which a static tier serves (L2) */
136
+ export function workerRequests(row) {
137
+ const paths = row.paths ?? {};
138
+ return row.requests - (paths[DEMAND_PATHS.boot] ?? 0) - (paths[DEMAND_PATHS.stub] ?? 0);
139
+ }
140
+ /** Worker-invocation equivalents with a stub and boot script on a static tier, per finished scenario (L2) */
141
+ export function demandWorkerCounts(reading) {
142
+ const rows = rowsOf(reading).filter(usable);
143
+ return demandCounts(reading).map((c) => {
144
+ const spool = rows.find((r) => r.arm === 'spool' && r.engine === c.engine && r.scenario === c.scenario);
145
+ return { ...c, spool: workerRequests(spool) };
146
+ });
147
+ }
148
+ /** network documents a spool arm sent: every request but the boot script, the stub, the beacon and a favicon (L2) */
149
+ export function documentRequests(row) {
150
+ const paths = row.paths ?? {};
151
+ return (workerRequests(row) - (paths['POST /.spool/beacon'] ?? 0) - (paths['GET /favicon.ico'] ?? 0));
152
+ }
153
+ /** network documents the spool arm of each finished scenario sent, in the `spool` field (L2) */
154
+ export function demandDocumentCounts(reading) {
155
+ const rows = rowsOf(reading).filter(usable);
156
+ return demandCounts(reading).map((c) => {
157
+ const spool = rows.find((r) => r.arm === 'spool' && r.engine === c.engine && r.scenario === c.scenario);
158
+ return { ...c, spool: documentRequests(spool) };
159
+ });
160
+ }
161
+ /** the three sizes from the single-day reading (ring) and the multi-day reading (boot, stub) */
162
+ export function libraryBytes(single, days) {
163
+ const one = demandCounts(single).find((c) => c.views === 1 && c.engine === 'chromium');
164
+ if (!one)
165
+ throw new RangeError('the single-day reading has no finished one-view Chromium pair');
166
+ const bytes = demandBytes(single, 'chromium', one.scenario);
167
+ const types = rowsOf(days)
168
+ .filter((r) => usable(r) && r.arm === 'spool')
169
+ .flatMap((r) => r.days ?? [])
170
+ .flatMap((d) => Object.entries(d.byType ?? {}));
171
+ const size = (type) => {
172
+ const found = types.find(([name, v]) => name === type && v.bytes > 0);
173
+ if (!found)
174
+ throw new RangeError(`the multi-day reading has no ${type} bytes`);
175
+ return found[1].bytes;
176
+ };
177
+ return { ring: bytes.spool - bytes.baseline, boot: size('asset'), stub: size('stub') };
178
+ }
179
+ /** the stub's header bytes on a 304, counted from the response object (L1, Mac, 2 s lease, lane ST) */
180
+ export const STUB_304_BYTES = 169;
181
+ /** the stub on a full re-check in the lane ST rig, bytes (L1) */
182
+ export const STUB_FULL_ST_BYTES = 137_529;
183
+ /**
184
+ * Bytes a client sends over `documents` network documents, one bootstrap and `stubFetches` stub
185
+ * fetches, with documents of `documentBytes` plus the ring on each (L2 over L1 sizes).
186
+ */
187
+ export function spoolBytes(args) {
188
+ const doc = args.documentBytes ?? DOCUMENT_BYTES.value;
189
+ return (args.documents * (doc + args.sizes.ring) +
190
+ (args.bootFetches ?? 1) * args.sizes.boot +
191
+ args.stubFetches * args.stubBytes);
192
+ }
193
+ /** the document views of a stub fetch that repay it: stub bytes over document bytes (L2) */
194
+ export const repaidAfter = (stubBytes, documentBytes = DOCUMENT_BYTES.value) => stubBytes / documentBytes;
195
+ /**
196
+ * Net bytes saved per read view as a share of the baseline document, for a workload with a worker.
197
+ * Held views save a document; a network view pays the ring; one bootstrap per `lifetimes` pays the
198
+ * boot script; each lifetime pays `stubFetches` stub fetches (L3 count). Negative is a loss.
199
+ */
200
+ export function netBytesShare(w, held, sizes, stubBytes, stubFetches = 1) {
201
+ const doc = DOCUMENT_BYTES.value;
202
+ const v = w.viewsPerLifetime;
203
+ const saved = held * doc -
204
+ (1 - held) * sizes.ring -
205
+ sizes.boot / (w.lifetimes * v) -
206
+ (stubFetches * stubBytes) / v;
207
+ return saved / doc;
208
+ }
209
+ /** the multiplier of a stage with a count pair; throws on a stage with none */
210
+ export function stageMultiplier(s) {
211
+ if (s.baseline === undefined || s.spool === undefined)
212
+ throw new RangeError(`stage ${s.stage} has no count pair`);
213
+ return multiplierOf(s.baseline, s.spool);
214
+ }
215
+ /**
216
+ * Stages before the library, with the counts each source printed. Rows come from the earlier stage reports, named by date.
217
+ * Every ratio is the two counts
218
+ * divided; no source's ratio is typed in.
219
+ */
220
+ export const HISTORY = [
221
+ {
222
+ quantity: 'origin',
223
+ stage: 'v0.4',
224
+ date: '2026-11-16',
225
+ figure: 'no count; bars of 3x to 1,500x proposed',
226
+ condition: 'targets, none measured',
227
+ layer: 'L3',
228
+ source: 'v0.4 interim, 2026-11-16',
229
+ status: 'withdrawn'
230
+ },
231
+ {
232
+ quantity: 'origin',
233
+ stage: 'original v1, minimal construction',
234
+ date: '2026-11-18',
235
+ baseline: 121,
236
+ spool: 3,
237
+ condition: "Chromium, Codex's 121-view mix, review model, loopback, all requests",
238
+ layer: 'L2',
239
+ source: 'v1 review, 2026-11-18',
240
+ status: 'superseded'
241
+ },
242
+ {
243
+ quantity: 'origin',
244
+ stage: 'original v1, Codex construction',
245
+ date: '2026-11-18',
246
+ baseline: 121,
247
+ spool: 4,
248
+ condition: "Chromium, same mix, Codex's construction",
249
+ layer: 'L2',
250
+ source: 'v1 review, 2026-11-18',
251
+ status: 'superseded'
252
+ },
253
+ {
254
+ quantity: 'origin',
255
+ stage: 'follow-ups, retrofit',
256
+ date: '2026-11-18',
257
+ baseline: 121,
258
+ spool: 4,
259
+ condition: 'Chromium and Firefox, same mix, local clone under workerd, no deployment',
260
+ layer: 'L2',
261
+ source: 'follow-ups, 2026-11-18',
262
+ status: 'superseded'
263
+ },
264
+ {
265
+ quantity: 'origin',
266
+ stage: 'follow-ups, retrofit, WebKit origin requests',
267
+ date: '2026-11-18',
268
+ baseline: 121,
269
+ spool: 23,
270
+ condition: 'WebKit, same mix, each navigation adds a script check',
271
+ layer: 'L2',
272
+ source: 'follow-ups, 2026-11-18',
273
+ status: 'superseded'
274
+ },
275
+ {
276
+ quantity: 'origin',
277
+ stage: 'follow-ups, retrofit, WebKit Worker calls',
278
+ date: '2026-11-18',
279
+ baseline: 121,
280
+ spool: 6,
281
+ condition: 'WebKit, same mix, Worker calls only, not origin requests',
282
+ layer: 'L2',
283
+ source: 'follow-ups, 2026-11-18',
284
+ status: 'superseded'
285
+ },
286
+ {
287
+ quantity: 'origin',
288
+ stage: 'first library run',
289
+ date: '2026-11-18',
290
+ baseline: 121,
291
+ spool: 9,
292
+ condition: 'Chromium, same mix, library, one run per arm',
293
+ layer: 'L2',
294
+ source: 'first library run, 2026-11-18',
295
+ status: 'superseded'
296
+ },
297
+ {
298
+ quantity: 'reader',
299
+ stage: 'original v1, daily reader',
300
+ date: '2026-11-18',
301
+ baseline: 600,
302
+ spool: 68,
303
+ condition: '20 views in 2 visits over 30 days, Chromium, review model count',
304
+ layer: 'L3',
305
+ source: 'v1 review, 2026-11-18',
306
+ status: 'superseded'
307
+ },
308
+ {
309
+ quantity: 'reader',
310
+ stage: 'original v1, engaged reader',
311
+ date: '2026-11-18',
312
+ baseline: 3000,
313
+ spool: 98,
314
+ condition: '100 views in 3 visits over 30 days, Chromium, review model count',
315
+ layer: 'L3',
316
+ source: 'v1 review, 2026-11-18',
317
+ status: 'superseded'
318
+ },
319
+ {
320
+ quantity: 'reader',
321
+ stage: 'original v1, one tab all day',
322
+ date: '2026-11-18',
323
+ baseline: 60000,
324
+ spool: 38,
325
+ condition: '2,000 views in one visit; a floor-based bound over a model count, never a measured count',
326
+ layer: 'L3',
327
+ source: 'v1 review, 2026-11-18',
328
+ status: 'superseded'
329
+ },
330
+ {
331
+ quantity: 'reader',
332
+ stage: 'review 2, daily reader',
333
+ date: '2026-11-18',
334
+ baseline: 601,
335
+ spool: 33,
336
+ condition: '600 views in 60 visits over 30 days, Chromium 157 headless on Linux, final construction',
337
+ layer: 'L3',
338
+ source: 'review 2, 2026-11-18',
339
+ status: 'superseded'
340
+ },
341
+ {
342
+ quantity: 'reader',
343
+ stage: 'review 2, engaged reader',
344
+ date: '2026-11-18',
345
+ baseline: 3001,
346
+ spool: 33,
347
+ condition: '3,000 views in 90 visits, same construction',
348
+ layer: 'L3',
349
+ source: 'review 2, 2026-11-18',
350
+ status: 'superseded'
351
+ },
352
+ {
353
+ quantity: 'reader',
354
+ stage: 'review 2, one tab all day, low end',
355
+ date: '2026-11-18',
356
+ baseline: 60001,
357
+ spool: 33,
358
+ condition: '60,000 in-page views; a floor-based bound over a model count, never a measured count',
359
+ layer: 'L3',
360
+ source: 'review 2, 2026-11-18',
361
+ status: 'superseded'
362
+ },
363
+ {
364
+ quantity: 'reader',
365
+ stage: 'review 2, one tab all day, high end',
366
+ date: '2026-11-18',
367
+ baseline: 60001,
368
+ spool: 28,
369
+ condition: 'same row at 28 requests; a floor-based bound, never a measured count',
370
+ layer: 'L3',
371
+ source: 'review 2, 2026-11-18',
372
+ status: 'superseded'
373
+ },
374
+ {
375
+ quantity: 'reader',
376
+ stage: 'review 2, population of 40 clients',
377
+ date: '2026-11-18',
378
+ baseline: 259,
379
+ spool: 112,
380
+ condition: 'mixed visits, same construction',
381
+ layer: 'L3',
382
+ source: 'review 2, 2026-11-18',
383
+ status: 'superseded'
384
+ },
385
+ {
386
+ quantity: 'reader',
387
+ stage: 'library today, earlier tree, daily reader',
388
+ date: '2026-11-20',
389
+ baseline: 5,
390
+ spool: 8,
391
+ condition: 'one view a day for 5 days, Chromium, before the third-view window of src/client/gate.ts; 495,557 B against 645 B',
392
+ layer: 'L2',
393
+ source: '`measurements/demand/2026-11-20-days.json`',
394
+ status: 'superseded'
395
+ },
396
+ {
397
+ quantity: 'free',
398
+ stage: 'follow-ups, retrofit',
399
+ date: '2026-11-18',
400
+ figure: 'views a day: 100,000 x 121 / 4 = 3,025,000 (Chromium, Firefox); 100,000 x 121 / 6 = 2,016,666 (WebKit)',
401
+ condition: 'Free-plan allowance over Worker calls; the source says it is not a deployed quota test',
402
+ layer: 'L2',
403
+ source: 'follow-ups, 2026-11-18',
404
+ status: 'superseded'
405
+ },
406
+ {
407
+ quantity: 'worker',
408
+ stage: 'original v1 and review 2, static host',
409
+ date: '2026-11-18',
410
+ figure: '121x, 600x, 3,000x and 60,000x over one Worker invocation',
411
+ condition: 'the stub, pack and client served as static files; the 1 is one measured session on a Free test Worker, the workloads are L3',
412
+ layer: 'L3',
413
+ source: 'v1 review and review 2, 2026-11-18',
414
+ status: 'current'
415
+ },
416
+ {
417
+ quantity: 'bytes',
418
+ stage: 'original v1',
419
+ date: '2026-11-18',
420
+ figure: 'spool sends more bytes than no spool at 10 views on 1 to 3 KB documents; no figure',
421
+ condition: 'direction only',
422
+ layer: 'L1',
423
+ source: 'v1 restart notes, 2026-11-18',
424
+ status: 'current'
425
+ },
426
+ {
427
+ quantity: 'bytes',
428
+ stage: 'v0.3 and v0.4, dataset update',
429
+ date: 'date not recorded',
430
+ figure: '227 to 232 B for one changed row against 2,236 to 191,744 B for a list refetch of 50 to 5,000 rows',
431
+ condition: 'synthetic rows; a dataset, not a document',
432
+ layer: 'L1',
433
+ source: 'v0.4 release notes',
434
+ status: 'current'
435
+ }
436
+ ];
437
+ /** library-today stages computed from the two demand readings (L1 counts, L2 ratios) */
438
+ export function libraryStages(single, days, daysFile = 'demand/2026-11-20-days.json', singleFile = 'demand/2026-11-20-single.json') {
439
+ const mark = (c, q, reading, what) => ({
440
+ quantity: q,
441
+ stage: q === 'reader'
442
+ ? `library today, final tree, ${c.engine}`
443
+ : `library today, ${c.engine}`,
444
+ date: reading.date,
445
+ baseline: c.baseline,
446
+ spool: c.spool,
447
+ condition: `${c.scenario}; ${what}`,
448
+ layer: 'L2',
449
+ source: `\`measurements/${q === 'reader' ? daysFile : singleFile}\``,
450
+ status: 'current'
451
+ });
452
+ const mix = demandCounts(single).filter((c) => c.views === 121);
453
+ const long = demandCounts(days);
454
+ const worker = demandWorkerCounts(single).filter((c) => c.views === 121);
455
+ return [
456
+ ...mix.map((c) => mark(c, 'origin', single, 'all origin requests, counted')),
457
+ ...long.map((c) => mark(c, 'reader', days, 'all origin requests, counted, one lease length')),
458
+ ...worker.map((c) => ({
459
+ ...mark(c, 'worker', single, 'stub and boot script on a static tier'),
460
+ stage: `library today, ${c.engine}, Worker-invocation equivalents`
461
+ }))
462
+ ];
463
+ }
464
+ // #endregion
465
+ /** read views a day at `baselineRequests` and `spoolRequests` per view, over the Free-plan allowance */
466
+ export function freeViewsPair(baseline, spool) {
467
+ const limit = CF_FREE_REQUESTS_PER_DAY.value;
468
+ return {
469
+ baseline: limit / baseline,
470
+ spool: spool === 0 ? Infinity : limit / spool,
471
+ multiplier: multiplierOf(baseline, spool)
472
+ };
473
+ }
@@ -1,10 +1,14 @@
1
1
  export * from './capacity.js';
2
2
  export * from './channels.js';
3
+ export * from './dataset.js';
4
+ export * from './demand.js';
3
5
  export * from './derive.js';
4
6
  export * from './economics.js';
7
+ export * from './headline.js';
5
8
  export * from './inputs.js';
6
9
  export * from './institution.js';
7
10
  export * from './ledger.js';
11
+ export * from './loops.js';
8
12
  export * from './measurement.js';
9
13
  export * from './model.js';
10
14
  export * from './thirdparty.js';
@@ -1,10 +1,14 @@
1
1
  export * from './capacity.js';
2
2
  export * from './channels.js';
3
+ export * from './dataset.js';
4
+ export * from './demand.js';
3
5
  export * from './derive.js';
4
6
  export * from './economics.js';
7
+ export * from './headline.js';
5
8
  export * from './inputs.js';
6
9
  export * from './institution.js';
7
10
  export * from './ledger.js';
11
+ export * from './loops.js';
8
12
  export * from './measurement.js';
9
13
  export * from './model.js';
10
14
  export * from './thirdparty.js';
@@ -139,3 +139,179 @@ export declare const TIERS: {
139
139
  readonly major: 0.65;
140
140
  readonly transformative: 0.9;
141
141
  };
142
+ /** grams per pound, the mass conversion behind eGRID's lb/MWh rates */
143
+ export declare const G_PER_LB = 453.59237;
144
+ /**
145
+ * Average retail electricity price in cents per kWh for 2025, from EIA Electric Power Annual Table
146
+ * 2.10 (L0). The table holds these five states. Any other state has no price here, and
147
+ * `electricityPrice` throws on it rather than guessing.
148
+ */
149
+ export declare const ELECTRICITY_PRICE: {
150
+ readonly US: {
151
+ readonly commercial: Input;
152
+ readonly industrial: Input;
153
+ };
154
+ readonly NH: {
155
+ readonly commercial: Input;
156
+ readonly industrial: Input;
157
+ };
158
+ readonly MA: {
159
+ readonly commercial: Input;
160
+ readonly industrial: Input;
161
+ };
162
+ readonly AZ: {
163
+ readonly commercial: Input;
164
+ readonly industrial: Input;
165
+ };
166
+ readonly WA: {
167
+ readonly commercial: Input;
168
+ readonly industrial: Input;
169
+ };
170
+ };
171
+ export type PriceState = keyof typeof ELECTRICITY_PRICE;
172
+ /** an eGRID2023 subregion; `US` is the national total */
173
+ export type EgridSubregion = 'US' | 'NEWE' | 'AZNM' | 'NWPP' | 'SRVC' | 'ERCT';
174
+ /**
175
+ * eGRID2023 total output CO2e per subregion, lb per MWh (L0). The boundary is stack emissions at the
176
+ * plant: no transmission or distribution losses and no upstream or construction emissions (eGRID
177
+ * Technical Guide, read in full).
178
+ */
179
+ export declare const EGRID_LB_PER_MWH: Readonly<Record<EgridSubregion, Input>>;
180
+ /**
181
+ * Ember's US carbon intensity of electricity generation, 2025, in gCO2e per kWh (L0). Ember states no
182
+ * boundary. It is printed beside the eGRID figure and never in its place.
183
+ */
184
+ export declare const EMBER_US_G_PER_KWH: Input;
185
+ /**
186
+ * Litres of water per kWh of data-centre electricity, consumed on site (L2, derived from LBNL 2024:
187
+ * 66 billion L in 2023 over 176 TWh). drupflare's worker docs use the same value.
188
+ */
189
+ export declare const WATER_DIRECT: Input;
190
+ /**
191
+ * Litres of water per kWh of electricity through generation (L2). drupflare's worker docs round
192
+ * LBNL's figure to 4.55.
193
+ */
194
+ export declare const WATER_INDIRECT: Input;
195
+ /** LBNL 2024's printed indirect water for data centres, 4.52 L/kWh (L0), shown beside `WATER_INDIRECT` */
196
+ export declare const WATER_INDIRECT_LBNL: Input;
197
+ /**
198
+ * Median bytes of a first view's home page (L0). The Web Almanac chapter's own figures conflict, from
199
+ * 2.16 to 2.41 MB; the midpoint is used here.
200
+ */
201
+ export declare const FIRST_VIEW_BYTES: Input;
202
+ /**
203
+ * Median bytes of a whole repeat view, pooled over every repeat-navigation reading (L1).
204
+ * `scripts/impact.ts` refuses to run if the readings give another median.
205
+ */
206
+ export declare const REPEAT_VIEW_BYTES: Input;
207
+ /** the high case of the ceiling scenario: every cut at its high value (L3) */
208
+ export declare const GOAL_HIGH_SHARE: Input;
209
+ /**
210
+ * Proposed goal shares of a site's own page-view footprint (L3). Proposed in the plan on 2026-11-03
211
+ * and not adopted; they are a research target, not a business figure.
212
+ */
213
+ export declare const GOAL_SHARES: readonly [0.025, 0.05, 0.1, 0.25];
214
+ /**
215
+ * drupflare's hosting saving per site a year against three deployments (L2, modelled). The
216
+ * production-baseline page of the worker docs prints these three; the peak-sized figure is the
217
+ * headline.
218
+ */
219
+ export declare const HOSTING_KWH_PER_SITE: {
220
+ readonly peak: {
221
+ readonly value: 390;
222
+ readonly unit: "kWh/site/yr";
223
+ readonly layer: "L2";
224
+ readonly source: "drupflare/worker docs/impact/energy/production-baseline.md: peak-sized, 3 regions, 12 nodes, 8 vCPU, 10%";
225
+ };
226
+ readonly production: {
227
+ readonly value: 224.2;
228
+ readonly unit: "kWh/site/yr";
229
+ readonly layer: "L2";
230
+ readonly source: "drupflare/worker docs/impact/energy/production-baseline.md: production, 3 regions, 12 nodes, 4 vCPU, 15%";
231
+ };
232
+ readonly floor: {
233
+ readonly value: 9.34;
234
+ readonly unit: "kWh/site/yr";
235
+ readonly layer: "L2";
236
+ readonly source: "drupflare/worker docs/impact/energy/production-baseline.md: worst case, one small VPS, 2 vCPU, 15%";
237
+ };
238
+ };
239
+ /** the request-law constants of `Q`, each a count from review/model.json or the review's constants table */
240
+ export declare const DEMAND: {
241
+ readonly bootstrapWorker: Input;
242
+ readonly bootstrapNoWorker: Input;
243
+ readonly contact: Input;
244
+ readonly contactInLease: Input;
245
+ readonly write: Input;
246
+ readonly inPage: Input;
247
+ readonly coldChromium: Input;
248
+ readonly coldRoute: Input;
249
+ readonly coldFirefox: Input;
250
+ readonly coldWebkitMac: Input;
251
+ readonly coldWebkitLinux: Input;
252
+ readonly coldTls: {
253
+ readonly value: 0;
254
+ readonly unit: "requests";
255
+ readonly layer: "L1";
256
+ readonly source: "review/REVIEW.md section 8, six cold restarts per engine against the deployed Worker; Chromium, Firefox and WebKit; measured on 2026-11-18; the count is Worker invocations";
257
+ };
258
+ readonly warmChromium: Input;
259
+ readonly warmFirefox: Input;
260
+ readonly warmWebkitMac: Input;
261
+ readonly warmWebkitLinux: Input;
262
+ };
263
+ /** counted views of the retrofit reading: one bootstrap, then the in-page and document views below */
264
+ export declare const RETROFIT_VIEWS: Input;
265
+ export declare const RETROFIT_IN_PAGE: Input;
266
+ export declare const RETROFIT_DOCUMENTS: Input;
267
+ /** requests that reached the origin over the retrofit views; WebKit includes its script check per navigation */
268
+ export declare const RETROFIT_ORIGIN: {
269
+ readonly chromium: Input;
270
+ readonly firefox: Input;
271
+ readonly webkit: Input;
272
+ };
273
+ /** Worker invocations over the retrofit views, per engine */
274
+ export declare const RETROFIT_WORKER: {
275
+ readonly chromium: Input;
276
+ readonly firefox: Input;
277
+ readonly webkit: Input;
278
+ };
279
+ /** the deployed session of section 8: the rig's phases, one Worker invocation each for the first document */
280
+ export declare const SESSION: {
281
+ readonly views: Input;
282
+ readonly heldReads: Input;
283
+ readonly documents: Input;
284
+ readonly restarts: Input;
285
+ };
286
+ /** the device layouts at 1,000, 10,000 and 100,000 rows, on the M2 Pro bench */
287
+ export declare const STORAGE: {
288
+ readonly rowsSmall: Input;
289
+ readonly rowsLarge: Input;
290
+ readonly rowsXl: Input;
291
+ readonly plainRowChromium: Input;
292
+ readonly plainRowFirefox: Input;
293
+ readonly plainRowWebkit: Input;
294
+ readonly packedRowChromium: Input;
295
+ readonly packedRowFirefox: Input;
296
+ readonly packedRowWebkit: Input;
297
+ readonly plainItemChromium: Input;
298
+ readonly plainItemFirefox: Input;
299
+ readonly plainItemWebkit: Input;
300
+ readonly packedItemChromium: Input;
301
+ readonly packedItemFirefox: Input;
302
+ readonly packedItemWebkit: Input;
303
+ readonly plainItemChromium100k: Input;
304
+ readonly packedItemChromium100k: Input;
305
+ readonly wirePacked: Input;
306
+ readonly wireBrotli: Input;
307
+ };
308
+ /** the 300-page crawls behind the real-page figures; each total is summed over the pages */
309
+ export declare const CRAWL: {
310
+ readonly pages: Input;
311
+ readonly docsText: Input;
312
+ readonly mdnText: Input;
313
+ readonly docsHtml: Input;
314
+ readonly mdnHtml: Input;
315
+ readonly docsHtmlEach: Input;
316
+ readonly mdnHtmlEach: Input;
317
+ };