@drupflare/spool 0.3.0 → 0.4.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 (90) hide show
  1. package/README.md +263 -41
  2. package/dist/cdn/client.js +1 -1
  3. package/dist/cdn/manifest.json +7 -7
  4. package/dist/cdn/spool-sw.js +1 -1
  5. package/dist/client/entry.js +33 -1
  6. package/dist/client/register.d.ts +23 -1
  7. package/dist/client/register.js +53 -7
  8. package/dist/protocol/config.d.ts +16 -1
  9. package/dist/protocol/config.js +3 -1
  10. package/dist/protocol/dataset.d.ts +183 -0
  11. package/dist/protocol/dataset.js +206 -0
  12. package/dist/protocol/envelope.d.ts +1 -0
  13. package/dist/protocol/envelope.js +2 -1
  14. package/dist/protocol/errors.d.ts +1 -1
  15. package/dist/protocol/graph.d.ts +23 -4
  16. package/dist/protocol/graph.js +34 -3
  17. package/dist/protocol/index.d.ts +3 -0
  18. package/dist/protocol/index.js +3 -0
  19. package/dist/protocol/plan.d.ts +100 -0
  20. package/dist/protocol/plan.js +661 -0
  21. package/dist/protocol/provision.d.ts +46 -0
  22. package/dist/protocol/provision.js +38 -0
  23. package/dist/protocol/query.d.ts +66 -5
  24. package/dist/protocol/query.js +103 -4
  25. package/dist/protocol/route.d.ts +6 -2
  26. package/dist/protocol/route.js +31 -3
  27. package/dist/protocol/write.d.ts +146 -0
  28. package/dist/protocol/write.js +101 -0
  29. package/dist/report/dataset.d.ts +48 -0
  30. package/dist/report/dataset.js +93 -0
  31. package/dist/report/derive.d.ts +285 -0
  32. package/dist/report/derive.js +676 -1
  33. package/dist/report/economics.d.ts +11 -1
  34. package/dist/report/economics.js +19 -1
  35. package/dist/report/index.d.ts +2 -0
  36. package/dist/report/index.js +2 -0
  37. package/dist/report/inputs.d.ts +97 -0
  38. package/dist/report/inputs.js +133 -0
  39. package/dist/report/institution.d.ts +188 -1
  40. package/dist/report/institution.js +146 -0
  41. package/dist/report/loops.d.ts +73 -0
  42. package/dist/report/loops.js +101 -0
  43. package/dist/report/measurement.d.ts +1 -1
  44. package/dist/report/measurement.js +3 -1
  45. package/dist/report/model.d.ts +2 -0
  46. package/dist/report/model.js +4 -0
  47. package/dist/report/thirdparty.d.ts +57 -0
  48. package/dist/report/thirdparty.js +111 -0
  49. package/dist/report/trim.d.ts +56 -0
  50. package/dist/report/trim.js +83 -1
  51. package/dist/server/dataset.d.ts +48 -0
  52. package/dist/server/dataset.js +308 -0
  53. package/dist/server/embedded.d.ts +3 -3
  54. package/dist/server/embedded.js +3 -3
  55. package/dist/server/index.d.ts +2 -0
  56. package/dist/server/index.js +2 -0
  57. package/dist/server/spool.d.ts +20 -0
  58. package/dist/server/spool.js +126 -18
  59. package/dist/server/write.d.ts +27 -0
  60. package/dist/server/write.js +127 -0
  61. package/dist/sw/analytics.d.ts +6 -0
  62. package/dist/sw/analytics.js +14 -0
  63. package/dist/sw/dataset-sync.d.ts +76 -0
  64. package/dist/sw/dataset-sync.js +149 -0
  65. package/dist/sw/dataset.d.ts +91 -0
  66. package/dist/sw/dataset.js +318 -0
  67. package/dist/sw/graph/index.d.ts +31 -1
  68. package/dist/sw/graph/index.js +57 -5
  69. package/dist/sw/graph/invalidate.d.ts +15 -3
  70. package/dist/sw/graph/invalidate.js +42 -4
  71. package/dist/sw/idb.js +78 -9
  72. package/dist/sw/partition.d.ts +6 -1
  73. package/dist/sw/partition.js +21 -2
  74. package/dist/sw/principal-dataset.d.ts +64 -0
  75. package/dist/sw/principal-dataset.js +254 -0
  76. package/dist/sw/render.d.ts +7 -2
  77. package/dist/sw/render.js +19 -5
  78. package/dist/sw/replica.d.ts +12 -3
  79. package/dist/sw/replica.js +40 -5
  80. package/dist/sw/runtime.d.ts +43 -2
  81. package/dist/sw/runtime.js +340 -24
  82. package/dist/sw/seal.d.ts +13 -0
  83. package/dist/sw/seal.js +13 -4
  84. package/dist/sw/static.d.ts +18 -0
  85. package/dist/sw/static.js +84 -1
  86. package/dist/sw/storage.d.ts +51 -1
  87. package/dist/sw/storage.js +33 -1
  88. package/dist/sw/write.d.ts +107 -0
  89. package/dist/sw/write.js +442 -0
  90. package/package.json +3 -2
@@ -1,4 +1,4 @@
1
- import { type HostPrice } from './inputs.js';
1
+ import { type EgridSubregion, type HostPrice, type Input } from './inputs.js';
2
2
  /** egress dollars for `localViews` that no longer send the document, at the host's tier price */
3
3
  export declare function egressUsd(localViews: number, host: HostPrice, bytes?: number): number;
4
4
  /** request dollars for `localViews`, one request each, where the host bills requests */
@@ -12,3 +12,13 @@ export declare function bandwidthUsd(localViews: number, host: HostPrice, bytes?
12
12
  export declare function perMillionViewsUsd(bytes: number, share: number, host: HostPrice): number;
13
13
  /** decimal GB a month that `annualLocalViews` no longer move */
14
14
  export declare function monthlyGb(annualLocalViews: number, bytes?: number): number;
15
+ /** the price record for a state and sector; throws on a state the price table does not hold */
16
+ export declare function electricityPrice(state: string, sector: 'commercial' | 'industrial'): Input;
17
+ /** dollars for `mwh` at `centsPerKwh` (one cent per kWh is $10 per MWh) */
18
+ export declare const usdForMwh: (mwh: number, centsPerKwh: number) => number;
19
+ /** grams CO2e per kWh from a rate in pounds per MWh, the unit eGRID prints */
20
+ export declare const gPerKwhFromLbPerMwh: (lbPerMwh: number) => number;
21
+ /** tonnes CO2e from megawatt-hours at `gPerKwh` */
22
+ export declare const tonnesFromMwh: (mwh: number, gPerKwh: number) => number;
23
+ /** the eGRID2023 rate of a subregion as grams per kWh; throws on a subregion the table does not hold */
24
+ export declare function egridGPerKwh(subregion: EgridSubregion): number;
@@ -1,4 +1,4 @@
1
- import { DOCUMENT_BYTES } from './inputs.js';
1
+ import { DOCUMENT_BYTES, EGRID_LB_PER_MWH, ELECTRICITY_PRICE, G_PER_LB } from './inputs.js';
2
2
  /** egress dollars for `localViews` that no longer send the document, at the host's tier price */
3
3
  export function egressUsd(localViews, host, bytes = DOCUMENT_BYTES.value) {
4
4
  return ((localViews * bytes) / host.bytesPerUnit) * host.egress.value;
@@ -22,3 +22,21 @@ export function perMillionViewsUsd(bytes, share, host) {
22
22
  export function monthlyGb(annualLocalViews, bytes = DOCUMENT_BYTES.value) {
23
23
  return (annualLocalViews * bytes) / 12 / 1e9;
24
24
  }
25
+ /** the price record for a state and sector; throws on a state the price table does not hold */
26
+ export function electricityPrice(state, sector) {
27
+ if (!Object.hasOwn(ELECTRICITY_PRICE, state))
28
+ throw new RangeError(`no electricity price for ${state}; the table holds ${Object.keys(ELECTRICITY_PRICE).join(', ')}`);
29
+ return ELECTRICITY_PRICE[state][sector];
30
+ }
31
+ /** dollars for `mwh` at `centsPerKwh` (one cent per kWh is $10 per MWh) */
32
+ export const usdForMwh = (mwh, centsPerKwh) => mwh * centsPerKwh * 10;
33
+ /** grams CO2e per kWh from a rate in pounds per MWh, the unit eGRID prints */
34
+ export const gPerKwhFromLbPerMwh = (lbPerMwh) => (lbPerMwh * G_PER_LB) / 1000;
35
+ /** tonnes CO2e from megawatt-hours at `gPerKwh` */
36
+ export const tonnesFromMwh = (mwh, gPerKwh) => (mwh * gPerKwh) / 1000;
37
+ /** the eGRID2023 rate of a subregion as grams per kWh; throws on a subregion the table does not hold */
38
+ export function egridGPerKwh(subregion) {
39
+ if (!Object.hasOwn(EGRID_LB_PER_MWH, subregion))
40
+ throw new RangeError(`no eGRID subregion ${subregion}`);
41
+ return gPerKwhFromLbPerMwh(EGRID_LB_PER_MWH[subregion].value);
42
+ }
@@ -1,10 +1,12 @@
1
1
  export * from './capacity.js';
2
2
  export * from './channels.js';
3
+ export * from './dataset.js';
3
4
  export * from './derive.js';
4
5
  export * from './economics.js';
5
6
  export * from './inputs.js';
6
7
  export * from './institution.js';
7
8
  export * from './ledger.js';
9
+ export * from './loops.js';
8
10
  export * from './measurement.js';
9
11
  export * from './model.js';
10
12
  export * from './thirdparty.js';
@@ -1,10 +1,12 @@
1
1
  export * from './capacity.js';
2
2
  export * from './channels.js';
3
+ export * from './dataset.js';
3
4
  export * from './derive.js';
4
5
  export * from './economics.js';
5
6
  export * from './inputs.js';
6
7
  export * from './institution.js';
7
8
  export * from './ledger.js';
9
+ export * from './loops.js';
8
10
  export * from './measurement.js';
9
11
  export * from './model.js';
10
12
  export * from './thirdparty.js';
@@ -139,3 +139,100 @@ 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
+ };
@@ -214,3 +214,136 @@ export const PANTHEON_OVERAGE = {
214
214
  };
215
215
  /** the three tiers, named by the share of annual views served with zero network */
216
216
  export const TIERS = { meaningful: 0.3, major: 0.65, transformative: 0.9 };
217
+ /** grams per pound, the mass conversion behind eGRID's lb/MWh rates */
218
+ export const G_PER_LB = 453.59237;
219
+ const cents = (value) => ({
220
+ value,
221
+ unit: 'cents/kWh',
222
+ layer: 'L0',
223
+ source: 'EIA Electric Power Annual 2025, Table 2.10, https://www.eia.gov/electricity/annual/html/epa_02_10.html (raw HTML read 2026-11-05)'
224
+ });
225
+ /**
226
+ * Average retail electricity price in cents per kWh for 2025, from EIA Electric Power Annual Table
227
+ * 2.10 (L0). The table holds these five states. Any other state has no price here, and
228
+ * `electricityPrice` throws on it rather than guessing.
229
+ */
230
+ export const ELECTRICITY_PRICE = {
231
+ US: { commercial: cents(13.37), industrial: cents(8.51) },
232
+ NH: { commercial: cents(20.11), industrial: cents(16.82) },
233
+ MA: { commercial: cents(23.1), industrial: cents(19.04) },
234
+ AZ: { commercial: cents(12.45), industrial: cents(8.05) },
235
+ WA: { commercial: cents(10.97), industrial: cents(7) }
236
+ };
237
+ const egrid = (value) => ({
238
+ value,
239
+ unit: 'lb/MWh',
240
+ layer: 'L0',
241
+ source: 'EPA eGRID2023, eGRID subregion total output emission rates, CO2e (https://www.epa.gov/egrid/summary-data), one WebFetch excerpt not cross-checked against the xlsx'
242
+ });
243
+ /**
244
+ * eGRID2023 total output CO2e per subregion, lb per MWh (L0). The boundary is stack emissions at the
245
+ * plant: no transmission or distribution losses and no upstream or construction emissions (eGRID
246
+ * Technical Guide, read in full).
247
+ */
248
+ export const EGRID_LB_PER_MWH = {
249
+ US: egrid(770.884),
250
+ NEWE: egrid(543.178),
251
+ AZNM: egrid(706.189),
252
+ NWPP: egrid(635.267),
253
+ SRVC: egrid(596.326),
254
+ ERCT: egrid(736.629)
255
+ };
256
+ /**
257
+ * Ember's US carbon intensity of electricity generation, 2025, in gCO2e per kWh (L0). Ember states no
258
+ * boundary. It is printed beside the eGRID figure and never in its place.
259
+ */
260
+ export const EMBER_US_G_PER_KWH = {
261
+ value: 384,
262
+ unit: 'gCO2e/kWh',
263
+ layer: 'L0',
264
+ source: 'Ember, Global Electricity Review 2026, major countries and regions (https://ember-energy.org/latest-insights/global-electricity-review-2026/major-countries-and-regions), WebFetch excerpt; another Ember page prints the same figure as 2024'
265
+ };
266
+ /**
267
+ * Litres of water per kWh of data-centre electricity, consumed on site (L2, derived from LBNL 2024:
268
+ * 66 billion L in 2023 over 176 TWh). drupflare's worker docs use the same value.
269
+ */
270
+ export const WATER_DIRECT = {
271
+ value: 0.375,
272
+ unit: 'L/kWh',
273
+ layer: 'L2',
274
+ source: 'drupflare/worker docs/impact/water.md, from LBNL 2024 (2023 data)'
275
+ };
276
+ /**
277
+ * Litres of water per kWh of electricity through generation (L2). drupflare's worker docs round
278
+ * LBNL's figure to 4.55.
279
+ */
280
+ export const WATER_INDIRECT = {
281
+ value: 4.55,
282
+ unit: 'L/kWh',
283
+ layer: 'L2',
284
+ source: 'drupflare/worker docs/impact/water.md, from LBNL 2024 (nearly 800 billion L through generation)'
285
+ };
286
+ /** LBNL 2024's printed indirect water for data centres, 4.52 L/kWh (L0), shown beside `WATER_INDIRECT` */
287
+ export const WATER_INDIRECT_LBNL = {
288
+ value: 4.52,
289
+ unit: 'L/kWh',
290
+ layer: 'L0',
291
+ source: 'LBNL 2024 United States Data Center Energy Usage Report, full text (4.35 for the whole US grid)'
292
+ };
293
+ /**
294
+ * Median bytes of a first view's home page (L0). The Web Almanac chapter's own figures conflict, from
295
+ * 2.16 to 2.41 MB; the midpoint is used here.
296
+ */
297
+ export const FIRST_VIEW_BYTES = {
298
+ value: 2_200_000,
299
+ unit: 'B',
300
+ layer: 'L0',
301
+ source: 'Web Almanac 2025, home-page weight median (mobile and desktop)'
302
+ };
303
+ /**
304
+ * Median bytes of a whole repeat view, pooled over every repeat-navigation reading (L1).
305
+ * `scripts/impact.ts` refuses to run if the readings give another median.
306
+ */
307
+ export const REPEAT_VIEW_BYTES = {
308
+ value: 66_343,
309
+ unit: 'B',
310
+ layer: 'L1',
311
+ source: 'measurements/repeat-nav, pooled whole-repeat-view median'
312
+ };
313
+ /** the high case of the ceiling scenario: every cut at its high value (L3) */
314
+ export const GOAL_HIGH_SHARE = {
315
+ value: 0.415,
316
+ unit: 'fraction',
317
+ layer: 'L3',
318
+ source: 'scenario, SPOOL_PLAN "How high can the share go" (2026-11-03): every cut at its high value'
319
+ };
320
+ /**
321
+ * Proposed goal shares of a site's own page-view footprint (L3). Proposed in the plan on 2026-11-03
322
+ * and not adopted; they are a research target, not a business figure.
323
+ */
324
+ export const GOAL_SHARES = [0.025, 0.05, 0.1, 0.25];
325
+ /**
326
+ * drupflare's hosting saving per site a year against three deployments (L2, modelled). The
327
+ * production-baseline page of the worker docs prints these three; the peak-sized figure is the
328
+ * headline.
329
+ */
330
+ export const HOSTING_KWH_PER_SITE = {
331
+ peak: {
332
+ value: 390,
333
+ unit: 'kWh/site/yr',
334
+ layer: 'L2',
335
+ source: 'drupflare/worker docs/impact/energy/production-baseline.md: peak-sized, 3 regions, 12 nodes, 8 vCPU, 10%'
336
+ },
337
+ production: {
338
+ value: 224.2,
339
+ unit: 'kWh/site/yr',
340
+ layer: 'L2',
341
+ source: 'drupflare/worker docs/impact/energy/production-baseline.md: production, 3 regions, 12 nodes, 4 vCPU, 15%'
342
+ },
343
+ floor: {
344
+ value: 9.34,
345
+ unit: 'kWh/site/yr',
346
+ layer: 'L2',
347
+ source: 'drupflare/worker docs/impact/energy/production-baseline.md: worst case, one small VPS, 2 vCPU, 15%'
348
+ }
349
+ };
@@ -1,4 +1,6 @@
1
+ import type { TimedView } from '../protocol/view.js';
1
2
  import type { CapacityPlan } from './capacity.js';
3
+ import { type EgridSubregion, type Input } from './inputs.js';
2
4
  /**
3
5
  * A server or instance the institution retired because spool made it unneeded. `watts` is the
4
6
  * draw of one unit; without it an instance has no energy figure and is listed as unpriced.
@@ -41,6 +43,38 @@ export type Observed = {
41
43
  /** metric value with spool, in unit; non-negative */
42
44
  after: number;
43
45
  };
46
+ /** a campus and the sites its host serves; what the economics and research blocks price */
47
+ export type InstitutionProfile = {
48
+ /** two-letter state code for the electricity price; a state the price table lacks throws */
49
+ state: string;
50
+ /** the eGRID2023 subregion the campus's electricity comes from */
51
+ subregion: EgridSubregion;
52
+ /** sites the host serves for the institution; the hosting saving is per site */
53
+ sites: number;
54
+ /** the institution's page views a year; the basis of the goal ladder */
55
+ viewsPerYear: number;
56
+ /** spool's attributional saving a year across all three boundaries, in MWh, from the caller's views channel */
57
+ attributionalMwh: number;
58
+ };
59
+ /** bytes one dataset holds on the device or on the server */
60
+ export type Holding = {
61
+ /** the dataset's name in the site's manifest */
62
+ dataset: string;
63
+ /** where the bytes sit */
64
+ where: 'device' | 'server';
65
+ /** bytes held; non-negative */
66
+ bytes: number;
67
+ };
68
+ /** the bytes held per dataset against the declared budget for each side */
69
+ export type StorageInputs = {
70
+ /** the declared budget in bytes, for the device and for the server */
71
+ budget: {
72
+ device: number;
73
+ server: number;
74
+ };
75
+ /** what each dataset holds; a side with no holding reads zero */
76
+ holdings: readonly Holding[];
77
+ };
44
78
  export type InstitutionInputs = {
45
79
  /** the capacity plan behind the potential channel */
46
80
  plan?: CapacityPlan;
@@ -52,10 +86,132 @@ export type InstitutionInputs = {
52
86
  invoices?: Invoices;
53
87
  /** servers and instances the institution retired */
54
88
  ledger?: readonly RetirementEntry[];
89
+ /** the campus and its sites, for the economics and research blocks */
90
+ institution?: InstitutionProfile;
91
+ /** bytes held per dataset on the device and the server, for the storage block */
92
+ storage?: StorageInputs;
93
+ /** the views spool recorded, for the trust block; read the worker's own counters from these */
94
+ views?: readonly TimedView[];
55
95
  };
56
96
  /** an observed change, then the three results of the capacity plan; none is added to another and any can be null or read zero */
57
97
  export type InstitutionReport = {
58
- /** what telemetry saw change, which is neither what the model says could change nor what was removed */
98
+ /** host-meter energy and its dollars; null without an institution profile */
99
+ economics: {
100
+ /** the state the prices are for */
101
+ state: string;
102
+ /** average industrial price, EIA 2025 */
103
+ industrial: Input;
104
+ /** average commercial price, EIA 2025 */
105
+ commercial: Input;
106
+ /** the hosting saving at each deployment, headline first; priced at both sector rates */
107
+ cases: {
108
+ /** the deployment the saving is against */
109
+ name: 'peak' | 'production' | 'floor';
110
+ /** kWh a site a year */
111
+ kwhPerSite: number;
112
+ /** the host-meter energy a year, in MWh */
113
+ mwh: number;
114
+ /** dollars at the industrial rate */
115
+ usdIndustrial: number;
116
+ /** dollars at the commercial rate */
117
+ usdCommercial: number;
118
+ }[];
119
+ /** the data-centre share of spool's attributional saving; it is already inside the hosting saving, so it is not added */
120
+ dataCentreMwh: number;
121
+ /** spool's attributional share outside the institution's meter: visitors' devices and networks */
122
+ offMeterMwh: number;
123
+ /** L2, derived from the profile and the hosting model */
124
+ layer: 'L2';
125
+ } | null;
126
+ /** bytes held against the declared budget; null without storage inputs */
127
+ storage: {
128
+ /** the declared budget, in bytes */
129
+ budget: {
130
+ device: number;
131
+ server: number;
132
+ };
133
+ /** bytes the holdings sum to, per side */
134
+ held: {
135
+ device: number;
136
+ server: number;
137
+ };
138
+ /** whether each side is within its budget */
139
+ within: {
140
+ device: boolean;
141
+ server: boolean;
142
+ };
143
+ /** the holdings as given */
144
+ holdings: readonly Holding[];
145
+ /** L1, measured here */
146
+ layer: 'L1';
147
+ } | null;
148
+ /** correctness counters from the views; null without views */
149
+ trust: {
150
+ /** views counted */
151
+ views: number;
152
+ /** shadow views the worker compared with the network's answer */
153
+ sampled: number;
154
+ /** sampled views whose local answer differed from the network's */
155
+ mismatches: number;
156
+ /** views the worker declined to answer locally or to render */
157
+ refused: number;
158
+ /** views answered from the network because a stored copy was outdated */
159
+ fallbacks: number;
160
+ /** counters the worker does not keep; read each as unknown, not as zero */
161
+ notCounted: readonly string[];
162
+ /** L1, measured here */
163
+ layer: 'L1';
164
+ } | null;
165
+ /** energy by meter boundary, carbon, water and the goal ladder; null without an institution profile */
166
+ research: {
167
+ /** spool's attributional saving by boundary; only the data-centre part is on a host's meter */
168
+ boundary: {
169
+ devices: {
170
+ mwh: number;
171
+ share: number;
172
+ };
173
+ networks: {
174
+ mwh: number;
175
+ share: number;
176
+ };
177
+ dataCentres: {
178
+ mwh: number;
179
+ share: number;
180
+ };
181
+ };
182
+ /** tonnes CO2e of the whole attributional saving, at the campus subregion and at Ember's national figure */
183
+ carbon: {
184
+ subregion: EgridSubregion;
185
+ gPerKwh: number;
186
+ tonnes: number;
187
+ ember: {
188
+ gPerKwh: number;
189
+ tonnes: number;
190
+ };
191
+ };
192
+ /** litres for the data-centre share; a locality figure, never summed across institutions */
193
+ water: {
194
+ directLitres: number;
195
+ indirectLitres: number;
196
+ indirectLbnlLitres: number;
197
+ };
198
+ /** the goal ladder: the saving at each share of the institution's own page-view footprint, kWh a year */
199
+ goal: {
200
+ viewsPerYear: number;
201
+ footprintMwh: number;
202
+ rungs: {
203
+ share: number;
204
+ kwh: number;
205
+ }[];
206
+ high: {
207
+ share: number;
208
+ kwh: number;
209
+ };
210
+ };
211
+ /** L2, derived from the profile and the published factors */
212
+ layer: 'L2';
213
+ } | null;
214
+ /** an observed change, read from the caller's measurement */
59
215
  observed: (Observed & {
60
216
  /** fractional drop from before to after; null when before is zero */
61
217
  reduction: number | null;
@@ -94,4 +250,35 @@ export type InstitutionReport = {
94
250
  /** sentence stating the physical saving, or that none was shown */
95
251
  statement: string;
96
252
  };
253
+ /** the page-view footprint of `viewsPerYear` views, in MWh a year, on the attributional basis */
254
+ export declare function footprintMwh(viewsPerYear: number): number;
255
+ /** one institution in a roll-up: its attributional saving and the subregion its electricity comes from */
256
+ export type InstitutionRow = {
257
+ /** a label for the row; the report prints it beside the institution's own litres */
258
+ name: string;
259
+ /** the eGRID2023 subregion the institution's electricity comes from */
260
+ subregion: EgridSubregion;
261
+ /** spool's attributional saving a year across all three boundaries, in MWh */
262
+ attributionalMwh: number;
263
+ };
264
+ /**
265
+ * A roll-up across institutions. Energy and carbon add up. Water does not add up: it is local, so
266
+ * each institution keeps its own litres and the type has no total.
267
+ */
268
+ export type Rollup = {
269
+ /** rows summed */
270
+ institutions: number;
271
+ /** attributional MWh a year, summed */
272
+ mwh: number;
273
+ /** tonnes CO2e a year, summed; each row uses its own subregion */
274
+ tonnes: number;
275
+ /** litres for each row's data-centre share, one entry per institution */
276
+ water: {
277
+ name: string;
278
+ directLitres: number;
279
+ indirectLitres: number;
280
+ }[];
281
+ };
282
+ /** sums energy and carbon across institutions and keeps water per institution */
283
+ export declare function rollUpInstitutions(rows: readonly InstitutionRow[]): Rollup;
97
284
  export declare function institutionReport(inputs: InstitutionInputs): InstitutionReport;