@managesome/eposmatic-toolkit 0.4.53 → 0.4.54

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 (61) hide show
  1. package/esm/helpers/materialized-reports/index.js +1 -0
  2. package/esm/helpers/materialized-reports/report-platform/definition.js +508 -0
  3. package/esm/helpers/materialized-reports/report-platform/index.js +4 -0
  4. package/esm/helpers/materialized-reports/report-platform/lifecycle/budget.js +27 -0
  5. package/esm/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.js +12 -0
  6. package/esm/helpers/materialized-reports/report-platform/lifecycle/entry-pages.js +121 -0
  7. package/esm/helpers/materialized-reports/report-platform/lifecycle/flat-projection.js +14 -0
  8. package/esm/helpers/materialized-reports/report-platform/lifecycle/index.js +8 -0
  9. package/esm/helpers/materialized-reports/report-platform/lifecycle/iteration-row.js +10 -0
  10. package/esm/helpers/materialized-reports/report-platform/lifecycle/run-stats.js +42 -0
  11. package/esm/helpers/materialized-reports/report-platform/lifecycle/scope-refs.js +28 -0
  12. package/esm/helpers/materialized-reports/report-platform/lifecycle/top-n.js +24 -0
  13. package/esm/helpers/materialized-reports/report-platform/registry.js +23 -0
  14. package/esm/helpers/materialized-reports/report-platform/validate-report-registry.js +214 -0
  15. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  16. package/lib/helpers/materialized-reports/index.js +1 -0
  17. package/lib/helpers/materialized-reports/report-platform/definition.d.ts +133 -0
  18. package/lib/helpers/materialized-reports/report-platform/definition.js +511 -0
  19. package/lib/helpers/materialized-reports/report-platform/index.d.ts +4 -0
  20. package/lib/helpers/materialized-reports/report-platform/index.js +20 -0
  21. package/lib/helpers/materialized-reports/report-platform/lifecycle/budget.d.ts +8 -0
  22. package/lib/helpers/materialized-reports/report-platform/lifecycle/budget.js +31 -0
  23. package/lib/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.d.ts +8 -0
  24. package/lib/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.js +16 -0
  25. package/lib/helpers/materialized-reports/report-platform/lifecycle/entry-pages.d.ts +40 -0
  26. package/lib/helpers/materialized-reports/report-platform/lifecycle/entry-pages.js +130 -0
  27. package/lib/helpers/materialized-reports/report-platform/lifecycle/flat-projection.d.ts +22 -0
  28. package/lib/helpers/materialized-reports/report-platform/lifecycle/flat-projection.js +17 -0
  29. package/lib/helpers/materialized-reports/report-platform/lifecycle/index.d.ts +8 -0
  30. package/lib/helpers/materialized-reports/report-platform/lifecycle/index.js +24 -0
  31. package/lib/helpers/materialized-reports/report-platform/lifecycle/iteration-row.d.ts +13 -0
  32. package/lib/helpers/materialized-reports/report-platform/lifecycle/iteration-row.js +13 -0
  33. package/lib/helpers/materialized-reports/report-platform/lifecycle/run-stats.d.ts +20 -0
  34. package/lib/helpers/materialized-reports/report-platform/lifecycle/run-stats.js +47 -0
  35. package/lib/helpers/materialized-reports/report-platform/lifecycle/scope-refs.d.ts +13 -0
  36. package/lib/helpers/materialized-reports/report-platform/lifecycle/scope-refs.js +31 -0
  37. package/lib/helpers/materialized-reports/report-platform/lifecycle/top-n.d.ts +16 -0
  38. package/lib/helpers/materialized-reports/report-platform/lifecycle/top-n.js +29 -0
  39. package/lib/helpers/materialized-reports/report-platform/registry.d.ts +13 -0
  40. package/lib/helpers/materialized-reports/report-platform/registry.js +31 -0
  41. package/lib/helpers/materialized-reports/report-platform/validate-report-registry.d.ts +20 -0
  42. package/lib/helpers/materialized-reports/report-platform/validate-report-registry.js +218 -0
  43. package/lib/tests/materialized-reports/characterization/delivery.characterization.test.d.ts +1 -0
  44. package/lib/tests/materialized-reports/characterization/delivery.characterization.test.js +229 -0
  45. package/lib/tests/materialized-reports/characterization/discount.characterization.test.d.ts +1 -0
  46. package/lib/tests/materialized-reports/characterization/discount.characterization.test.js +99 -0
  47. package/lib/tests/materialized-reports/characterization/fixtures.d.ts +30 -0
  48. package/lib/tests/materialized-reports/characterization/fixtures.js +402 -0
  49. package/lib/tests/materialized-reports/characterization/golden.d.ts +18 -0
  50. package/lib/tests/materialized-reports/characterization/golden.js +127 -0
  51. package/lib/tests/materialized-reports/characterization/overview.characterization.test.d.ts +1 -0
  52. package/lib/tests/materialized-reports/characterization/overview.characterization.test.js +69 -0
  53. package/lib/tests/materialized-reports/characterization/prep-time.characterization.test.d.ts +1 -0
  54. package/lib/tests/materialized-reports/characterization/prep-time.characterization.test.js +102 -0
  55. package/lib/tests/materialized-reports/report-platform/lifecycle-primitives.test.d.ts +1 -0
  56. package/lib/tests/materialized-reports/report-platform/lifecycle-primitives.test.js +177 -0
  57. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.d.ts +1 -0
  58. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.js +214 -0
  59. package/lib/tests/materialized-reports/report-platform/registry-validation.test.d.ts +1 -0
  60. package/lib/tests/materialized-reports/report-platform/registry-validation.test.js +103 -0
  61. package/package.json +4 -2
@@ -53,3 +53,4 @@ export * from './tenant-delivery-formatter';
53
53
  export * from './tenant-prep-time-formatter';
54
54
  export * from './tenant-sales-overview-formatter';
55
55
  export * from './tenant-sales-overview-helpers';
56
+ export * from './report-platform';
@@ -0,0 +1,508 @@
1
+ import { MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_ENTRY_SCOPES, MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_REPORT_SCOPES, MATERIALIZED_DISCOUNT_REPORT_SCOPES, MATERIALIZED_PREP_TIME_ITEM_SCOPES, MATERIALIZED_PREP_TIME_REPORT_SCOPES, MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_TYPE_ENUM, ALL_MATERIALIZED_REPORT_SCOPES, } from '../../../constants/MATERIALIZED_REPORTS';
2
+ import { REPORT_KEY_ENUM } from '../../reporting-contract/report-contract';
3
+ /**
4
+ * PHASE 2 — DECLARATIVE REPORT DEFINITIONS.
5
+ *
6
+ * This module is METADATA ONLY. It must not import Mongoose, Express, database
7
+ * code, workers-service or operations-service. Metric compilation, document
8
+ * schemas and formatters stay report-specific.
9
+ *
10
+ * Schema versions are declared as literals here so this module stays free of
11
+ * schema/model imports. The conformance suite compares every literal with the
12
+ * exported model constant; drift fails the build.
13
+ */
14
+ export var REPORT_DEFINITION_STATUS;
15
+ (function (REPORT_DEFINITION_STATUS) {
16
+ REPORT_DEFINITION_STATUS["PRODUCTION"] = "PRODUCTION";
17
+ REPORT_DEFINITION_STATUS["READ_ONLY"] = "READ_ONLY";
18
+ REPORT_DEFINITION_STATUS["PLANNED"] = "PLANNED";
19
+ })(REPORT_DEFINITION_STATUS || (REPORT_DEFINITION_STATUS = {}));
20
+ export var REPORT_ENTRY_STORAGE;
21
+ (function (REPORT_ENTRY_STORAGE) {
22
+ /** No itemized collection. */
23
+ REPORT_ENTRY_STORAGE["NONE"] = "NONE";
24
+ /** One entry document per (tenant, scope, field); Prep Time today. */
25
+ REPORT_ENTRY_STORAGE["ONE_PER_SCOPE"] = "ONE_PER_SCOPE";
26
+ /** One entry document per source day; Discounts and Delivery today. */
27
+ REPORT_ENTRY_STORAGE["PAGE_PER_SOURCE_DAY"] = "PAGE_PER_SOURCE_DAY";
28
+ })(REPORT_ENTRY_STORAGE || (REPORT_ENTRY_STORAGE = {}));
29
+ export var REPORT_ENTRY_SPLIT;
30
+ (function (REPORT_ENTRY_SPLIT) {
31
+ REPORT_ENTRY_SPLIT["NONE"] = "NONE";
32
+ /** Deterministic `page#0`, `page#1`, ... when one page exceeds its budget. */
33
+ REPORT_ENTRY_SPLIT["DETERMINISTIC_SUBPAGES"] = "DETERMINISTIC_SUBPAGES";
34
+ })(REPORT_ENTRY_SPLIT || (REPORT_ENTRY_SPLIT = {}));
35
+ export var REPORT_WRITE_GUARD;
36
+ (function (REPORT_WRITE_GUARD) {
37
+ REPORT_WRITE_GUARD["NONE"] = "NONE";
38
+ REPORT_WRITE_GUARD["WATERMARK"] = "WATERMARK";
39
+ REPORT_WRITE_GUARD["WATERMARK_AND_DIGEST"] = "WATERMARK_AND_DIGEST";
40
+ })(REPORT_WRITE_GUARD || (REPORT_WRITE_GUARD = {}));
41
+ export var REPORT_LIVE_SOURCE;
42
+ (function (REPORT_LIVE_SOURCE) {
43
+ REPORT_LIVE_SOURCE["RAW"] = "RAW";
44
+ REPORT_LIVE_SOURCE["RAW_PLUS_MATERIALIZED"] = "RAW_PLUS_MATERIALIZED";
45
+ })(REPORT_LIVE_SOURCE || (REPORT_LIVE_SOURCE = {}));
46
+ export var REPORT_HISTORICAL_LENS;
47
+ (function (REPORT_HISTORICAL_LENS) {
48
+ REPORT_HISTORICAL_LENS["DOCUMENT_FOLD"] = "DOCUMENT_FOLD";
49
+ REPORT_HISTORICAL_LENS["COUNTER_ROWS"] = "COUNTER_ROWS";
50
+ })(REPORT_HISTORICAL_LENS || (REPORT_HISTORICAL_LENS = {}));
51
+ export var REPORT_CURSOR_KIND;
52
+ (function (REPORT_CURSOR_KIND) {
53
+ REPORT_CURSOR_KIND["NONE"] = "NONE";
54
+ REPORT_CURSOR_KIND["KEYSET_STRUCTURED"] = "KEYSET_STRUCTURED";
55
+ REPORT_CURSOR_KIND["SIGNED_QUERY"] = "SIGNED_QUERY";
56
+ })(REPORT_CURSOR_KIND || (REPORT_CURSOR_KIND = {}));
57
+ export var REPORT_PROJECTION;
58
+ (function (REPORT_PROJECTION) {
59
+ REPORT_PROJECTION["FLAT_DRILLDOWN"] = "FLAT_DRILLDOWN";
60
+ REPORT_PROJECTION["DISCOUNT_SOURCES"] = "DISCOUNT_SOURCES";
61
+ REPORT_PROJECTION["DELIVERY_GEO"] = "DELIVERY_GEO";
62
+ })(REPORT_PROJECTION || (REPORT_PROJECTION = {}));
63
+ export var REPORT_RETENTION_UNIT;
64
+ (function (REPORT_RETENTION_UNIT) {
65
+ REPORT_RETENTION_UNIT["DAY"] = "DAY";
66
+ REPORT_RETENTION_UNIT["MONTH"] = "MONTH";
67
+ })(REPORT_RETENTION_UNIT || (REPORT_RETENTION_UNIT = {}));
68
+ const DOCUMENT_BUDGET = 15 * 1024 * 1024;
69
+ const GEO_SCOPE_BUDGET = 2 * 1024 * 1024;
70
+ const FLAT_ROWS = {
71
+ name: 'materialized_report_drilldown_rows',
72
+ schemaVersion: 1,
73
+ budgetBytes: DOCUMENT_BUDGET,
74
+ enforced: false,
75
+ validatorFile: null,
76
+ validatorDebt: 'No schema validator exists for the flat drill-down rows yet.',
77
+ indexOwner: 'toolkit:MATERIALIZED_REPORT_DRILLDOWN_ROWS_INDEX_OPTIONS',
78
+ migrationId: null,
79
+ };
80
+ const FLAT_SCOPES = {
81
+ name: 'materialized_report_drilldown_scopes',
82
+ schemaVersion: 1,
83
+ budgetBytes: DOCUMENT_BUDGET,
84
+ enforced: false,
85
+ validatorFile: null,
86
+ validatorDebt: 'No schema validator exists for the flat drill-down scopes yet.',
87
+ indexOwner: 'toolkit:MATERIALIZED_REPORT_DRILLDOWN_SCOPES_INDEX_OPTIONS',
88
+ migrationId: null,
89
+ };
90
+ const CLIENT_KEY_FILTERS = [
91
+ {
92
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
93
+ kind: 'KEY_COMPONENT',
94
+ mode: 'CLIENT',
95
+ appliesTo: 'BOTH',
96
+ },
97
+ {
98
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM,
99
+ kind: 'KEY_COMPONENT',
100
+ mode: 'CLIENT',
101
+ appliesTo: 'BOTH',
102
+ },
103
+ { id: 'DAY_INDEX', kind: 'ROW', mode: 'CLIENT', appliesTo: 'SUMMARY' },
104
+ ];
105
+ const OVERVIEW_DEFINITION = {
106
+ key: REPORT_KEY_ENUM.OVERVIEW,
107
+ segment: 'overview',
108
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_SALES_OVERVIEW,
109
+ capabilities: { live: true, historical: true, details: false },
110
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
111
+ report: {
112
+ name: 'materialized_tenant_sales_overview_reports',
113
+ schemaVersion: 1,
114
+ budgetBytes: DOCUMENT_BUDGET,
115
+ enforced: false,
116
+ validatorFile: 'materialized_tenant_sales_overview_reports.bson',
117
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS',
118
+ migrationId: null,
119
+ },
120
+ sideCollections: [
121
+ {
122
+ name: 'materialized_tenant_credit_bills',
123
+ schemaVersion: 1,
124
+ budgetBytes: DOCUMENT_BUDGET,
125
+ enforced: false,
126
+ validatorFile: 'materialized_tenant_credit_bills.bson',
127
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_CREDIT_BILLS_INDEX_OPTIONS',
128
+ migrationId: null,
129
+ },
130
+ ],
131
+ reportScopes: [...ALL_MATERIALIZED_REPORT_SCOPES],
132
+ entryScopes: [],
133
+ entryStorage: REPORT_ENTRY_STORAGE.NONE,
134
+ entrySplit: REPORT_ENTRY_SPLIT.NONE,
135
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
136
+ maxEntryScope: null,
137
+ projections: [],
138
+ budgets: {
139
+ materialized_tenant_sales_overview_reports: DOCUMENT_BUDGET,
140
+ materialized_tenant_credit_bills: DOCUMENT_BUDGET,
141
+ },
142
+ retention: [],
143
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK_AND_DIGEST,
144
+ liveSource: REPORT_LIVE_SOURCE.RAW_PLUS_MATERIALIZED,
145
+ historicalLens: REPORT_HISTORICAL_LENS.DOCUMENT_FOLD,
146
+ completeness: { summary: 'ALL_SCOPES', details: 'NONE' },
147
+ filters: CLIENT_KEY_FILTERS,
148
+ cursor: REPORT_CURSOR_KIND.NONE,
149
+ adapters: {
150
+ writer: 'materializeOverviewReport',
151
+ live: 'getLiveTenantSalesOverviewReports',
152
+ historical: 'getMaterializedTenantSalesOverviewReports',
153
+ },
154
+ owner: 'reporting-platform',
155
+ notes: [
156
+ 'Map-only counters: no sales_overview_counter_rows.',
157
+ 'LIVE is raw + stored credit ledger and resolves the running day server-side.',
158
+ 'Writes the credit ledger and may patch prior issue-day counters.',
159
+ ],
160
+ };
161
+ const DISCOUNTS_DEFINITION = {
162
+ key: REPORT_KEY_ENUM.DISCOUNTS,
163
+ segment: 'discounts',
164
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DISCOUNT_REPORTS,
165
+ capabilities: { live: true, historical: true, details: true },
166
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
167
+ report: {
168
+ name: 'materialized_tenant_discount_reports',
169
+ schemaVersion: 1,
170
+ budgetBytes: DOCUMENT_BUDGET,
171
+ enforced: false,
172
+ validatorFile: 'materialized_tenant_discount_reports.bson',
173
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DISCOUNT_REPORTS_INDEX_OPTIONS',
174
+ migrationId: 'discount-entry-page-index',
175
+ },
176
+ entries: {
177
+ name: 'materialized_tenant_discount_entries',
178
+ schemaVersion: 1,
179
+ budgetBytes: DOCUMENT_BUDGET,
180
+ enforced: false,
181
+ validatorFile: 'materialized_tenant_discount_entries.bson',
182
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DISCOUNT_ENTRIES_INDEX_OPTIONS',
183
+ migrationId: 'discount-entry-page-index',
184
+ },
185
+ sideCollections: [
186
+ {
187
+ name: 'materialized_tenant_discount_sources',
188
+ schemaVersion: 1,
189
+ budgetBytes: DOCUMENT_BUDGET,
190
+ enforced: false,
191
+ validatorFile: null,
192
+ validatorDebt: 'No schema validator exists for the discount source projection yet.',
193
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS',
194
+ migrationId: null,
195
+ },
196
+ FLAT_ROWS,
197
+ FLAT_SCOPES,
198
+ ],
199
+ reportScopes: [...MATERIALIZED_DISCOUNT_REPORT_SCOPES],
200
+ entryScopes: [...MATERIALIZED_DISCOUNT_REPORT_SCOPES],
201
+ entryStorage: REPORT_ENTRY_STORAGE.PAGE_PER_SOURCE_DAY,
202
+ entrySplit: REPORT_ENTRY_SPLIT.NONE,
203
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
204
+ maxEntryScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
205
+ projections: [REPORT_PROJECTION.DISCOUNT_SOURCES, REPORT_PROJECTION.FLAT_DRILLDOWN],
206
+ budgets: {
207
+ materialized_tenant_discount_reports: DOCUMENT_BUDGET,
208
+ materialized_tenant_discount_entries: DOCUMENT_BUDGET,
209
+ materialized_tenant_discount_sources: DOCUMENT_BUDGET,
210
+ materialized_report_drilldown_rows: DOCUMENT_BUDGET,
211
+ materialized_report_drilldown_scopes: DOCUMENT_BUDGET,
212
+ },
213
+ retention: [],
214
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK_AND_DIGEST,
215
+ liveSource: REPORT_LIVE_SOURCE.RAW,
216
+ historicalLens: REPORT_HISTORICAL_LENS.COUNTER_ROWS,
217
+ completeness: { summary: 'NONE', details: 'FLAT_PROJECTION' },
218
+ filters: [
219
+ ...CLIENT_KEY_FILTERS,
220
+ {
221
+ id: 'DETAILS_VIEW',
222
+ kind: 'REQUEST',
223
+ mode: 'SERVER',
224
+ appliesTo: 'DETAILS',
225
+ },
226
+ {
227
+ id: 'SOURCE_KEY_LEVEL',
228
+ kind: 'REQUEST',
229
+ mode: 'SERVER',
230
+ appliesTo: 'DETAILS',
231
+ },
232
+ ],
233
+ cursor: REPORT_CURSOR_KIND.KEYSET_STRUCTURED,
234
+ adapters: {
235
+ writer: 'materializeDiscountReport',
236
+ live: 'getLiveTenantDiscountReports',
237
+ historical: 'getMaterializedTenantDiscountReports',
238
+ details: 'getMaterializedDiscountDetailsPage',
239
+ },
240
+ owner: 'reporting-platform',
241
+ notes: [
242
+ 'Month-capped scope set; a wider selection is refused, never narrowed.',
243
+ 'Page-partitioned entries; no #N splitter and no budget assertion today.',
244
+ 'Derived source projection has no independent iteration history.',
245
+ ],
246
+ };
247
+ const PREP_TIME_DEFINITION = {
248
+ key: REPORT_KEY_ENUM.PREP_TIME,
249
+ segment: 'prep-time',
250
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_PREP_TIME_REPORTS,
251
+ capabilities: { live: true, historical: true, details: true },
252
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
253
+ report: {
254
+ name: 'materialized_tenant_prep_time_reports',
255
+ schemaVersion: 1,
256
+ budgetBytes: DOCUMENT_BUDGET,
257
+ enforced: false,
258
+ validatorFile: 'materialized_tenant_prep_time_reports.bson',
259
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_PREP_TIME_REPORTS_INDEX_OPTIONS',
260
+ migrationId: null,
261
+ },
262
+ entries: {
263
+ name: 'materialized_tenant_prep_time_entries',
264
+ schemaVersion: 1,
265
+ budgetBytes: DOCUMENT_BUDGET,
266
+ enforced: false,
267
+ validatorFile: 'materialized_tenant_prep_time_entries.bson',
268
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_PREP_TIME_ENTRIES_INDEX_OPTIONS',
269
+ migrationId: null,
270
+ },
271
+ sideCollections: [FLAT_ROWS, FLAT_SCOPES],
272
+ reportScopes: [...MATERIALIZED_PREP_TIME_REPORT_SCOPES],
273
+ entryScopes: [...MATERIALIZED_PREP_TIME_ITEM_SCOPES],
274
+ entryStorage: REPORT_ENTRY_STORAGE.ONE_PER_SCOPE,
275
+ entrySplit: REPORT_ENTRY_SPLIT.NONE,
276
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
277
+ maxEntryScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
278
+ projections: [REPORT_PROJECTION.FLAT_DRILLDOWN],
279
+ budgets: {
280
+ materialized_tenant_prep_time_reports: DOCUMENT_BUDGET,
281
+ materialized_tenant_prep_time_entries: DOCUMENT_BUDGET,
282
+ materialized_report_drilldown_rows: DOCUMENT_BUDGET,
283
+ materialized_report_drilldown_scopes: DOCUMENT_BUDGET,
284
+ },
285
+ retention: [],
286
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK,
287
+ liveSource: REPORT_LIVE_SOURCE.RAW,
288
+ historicalLens: REPORT_HISTORICAL_LENS.COUNTER_ROWS,
289
+ completeness: { summary: 'NONE', details: 'FLAT_PROJECTION' },
290
+ filters: [
291
+ ...CLIENT_KEY_FILTERS,
292
+ { id: 'DETAILS_VIEW', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
293
+ { id: 'LATE_ONLY', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
294
+ { id: 'ITEM_ID', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
295
+ {
296
+ id: 'EXCLUDE_CANCELLED',
297
+ kind: 'REQUEST',
298
+ mode: 'SERVER',
299
+ appliesTo: 'DETAILS',
300
+ },
301
+ ],
302
+ cursor: REPORT_CURSOR_KIND.SIGNED_QUERY,
303
+ adapters: {
304
+ writer: 'materializePrepTimeReport',
305
+ live: 'getLiveTenantPrepTimeReports',
306
+ historical: 'getMaterializedTenantPrepTimeReports',
307
+ details: 'getMaterializedPrepTimeDetailsPage',
308
+ },
309
+ owner: 'reporting-platform',
310
+ notes: [
311
+ 'Coverage-first counters: MEASURED/UNMEASURED anchor split and target provenance.',
312
+ 'No hour scope; entries are one document per scope, not pages.',
313
+ 'Item reads are capped at 31 effective days at the route.',
314
+ ],
315
+ };
316
+ const DELIVERY_DEFINITION = {
317
+ key: REPORT_KEY_ENUM.DELIVERY,
318
+ segment: 'delivery',
319
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DELIVERY_REPORTS,
320
+ capabilities: { live: true, historical: true, details: true },
321
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
322
+ report: {
323
+ name: 'materialized_tenant_delivery_reports',
324
+ schemaVersion: 2,
325
+ budgetBytes: MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES,
326
+ enforced: true,
327
+ validatorFile: 'materialized_tenant_delivery_reports.bson',
328
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DELIVERY_REPORTS_INDEX_OPTIONS',
329
+ migrationId: 'delivery-page-index-2026-10-27',
330
+ },
331
+ entries: {
332
+ name: 'materialized_tenant_delivery_entries',
333
+ schemaVersion: 3,
334
+ budgetBytes: MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES,
335
+ enforced: true,
336
+ validatorFile: 'materialized_tenant_delivery_entries.bson',
337
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DELIVERY_ENTRIES_INDEX_OPTIONS',
338
+ migrationId: 'delivery-page-index-2026-10-27',
339
+ },
340
+ sideCollections: [
341
+ {
342
+ name: 'materialized_tenant_delivery_geo_cells',
343
+ schemaVersion: 1,
344
+ budgetBytes: MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES,
345
+ enforced: true,
346
+ validatorFile: 'materialized_tenant_delivery_geo_cells.bson',
347
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_INDEX_OPTIONS',
348
+ migrationId: 'delivery-page-index-2026-10-27',
349
+ },
350
+ {
351
+ name: 'materialized_tenant_delivery_geo_scopes',
352
+ schemaVersion: 1,
353
+ budgetBytes: GEO_SCOPE_BUDGET,
354
+ enforced: false,
355
+ validatorFile: 'materialized_tenant_delivery_geo_scopes.bson',
356
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_INDEX_OPTIONS',
357
+ migrationId: 'delivery-page-index-2026-10-27',
358
+ },
359
+ FLAT_ROWS,
360
+ FLAT_SCOPES,
361
+ ],
362
+ reportScopes: [...MATERIALIZED_DELIVERY_REPORT_SCOPES],
363
+ entryScopes: [...MATERIALIZED_DELIVERY_ENTRY_SCOPES],
364
+ entryStorage: REPORT_ENTRY_STORAGE.PAGE_PER_SOURCE_DAY,
365
+ entrySplit: REPORT_ENTRY_SPLIT.DETERMINISTIC_SUBPAGES,
366
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
367
+ maxEntryScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
368
+ projections: [REPORT_PROJECTION.FLAT_DRILLDOWN, REPORT_PROJECTION.DELIVERY_GEO],
369
+ budgets: {
370
+ materialized_tenant_delivery_reports: MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES,
371
+ materialized_tenant_delivery_entries: MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES,
372
+ materialized_tenant_delivery_geo_cells: MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES,
373
+ materialized_tenant_delivery_geo_scopes: GEO_SCOPE_BUDGET,
374
+ materialized_report_drilldown_rows: DOCUMENT_BUDGET,
375
+ materialized_report_drilldown_scopes: DOCUMENT_BUDGET,
376
+ },
377
+ retention: [
378
+ {
379
+ collection: 'materialized_tenant_delivery_geo_cells',
380
+ unit: REPORT_RETENTION_UNIT.DAY,
381
+ amount: 90,
382
+ },
383
+ {
384
+ collection: 'materialized_tenant_delivery_geo_cells',
385
+ unit: REPORT_RETENTION_UNIT.MONTH,
386
+ amount: 24,
387
+ },
388
+ ],
389
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK,
390
+ liveSource: REPORT_LIVE_SOURCE.RAW,
391
+ historicalLens: REPORT_HISTORICAL_LENS.COUNTER_ROWS,
392
+ completeness: { summary: 'NONE', details: 'FLAT_PROJECTION' },
393
+ filters: [
394
+ {
395
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
396
+ kind: 'KEY_COMPONENT',
397
+ mode: 'SERVER',
398
+ appliesTo: 'BOTH',
399
+ },
400
+ {
401
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM,
402
+ kind: 'KEY_COMPONENT',
403
+ mode: 'SERVER',
404
+ appliesTo: 'BOTH',
405
+ },
406
+ {
407
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.CITY,
408
+ kind: 'KEY_COMPONENT',
409
+ mode: 'SERVER',
410
+ appliesTo: 'BOTH',
411
+ },
412
+ { id: 'RIDER_ID', kind: 'ROW', mode: 'SERVER', appliesTo: 'BOTH' },
413
+ { id: 'DETAILS_VIEW', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
414
+ ],
415
+ cursor: REPORT_CURSOR_KIND.KEYSET_STRUCTURED,
416
+ adapters: {
417
+ writer: 'materializeDeliveryReport',
418
+ live: 'getLiveTenantDeliveryReports',
419
+ historical: 'getMaterializedTenantDeliveryReports',
420
+ details: 'getMaterializedDeliveryDetailsPage',
421
+ },
422
+ owner: 'reporting-platform',
423
+ notes: [
424
+ 'Separate H3 geo collection and cap metadata; live geo is computed in memory.',
425
+ 'Cross-day completion re-materializes the prior ORDER day within the same transaction.',
426
+ 'Page entries split deterministically into #N sub-pages.',
427
+ 'Historical totals do not pin schema_version today (baseline debt).',
428
+ ],
429
+ };
430
+ export const REPORT_DEFINITIONS = {
431
+ [OVERVIEW_DEFINITION.key]: OVERVIEW_DEFINITION,
432
+ [DISCOUNTS_DEFINITION.key]: DISCOUNTS_DEFINITION,
433
+ [PREP_TIME_DEFINITION.key]: PREP_TIME_DEFINITION,
434
+ [DELIVERY_DEFINITION.key]: DELIVERY_DEFINITION,
435
+ };
436
+ export const PRODUCTION_REPORT_DEFINITIONS = [
437
+ OVERVIEW_DEFINITION,
438
+ DISCOUNTS_DEFINITION,
439
+ PREP_TIME_DEFINITION,
440
+ DELIVERY_DEFINITION,
441
+ ];
442
+ export const REPORT_REGISTRY_EXEMPTIONS = {
443
+ [REPORT_KEY_ENUM.CASH_IN_OUT]: {
444
+ key: REPORT_KEY_ENUM.CASH_IN_OUT,
445
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
446
+ reason: 'Read adapters exist but there is no production END_TENANT_DAY writer.',
447
+ },
448
+ [REPORT_KEY_ENUM.SALES_COMPARISON]: {
449
+ key: REPORT_KEY_ENUM.SALES_COMPARISON,
450
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
451
+ reason: 'Read adapters exist but there is no production END_TENANT_DAY writer.',
452
+ },
453
+ [REPORT_KEY_ENUM.HOURLY_COMPARISON]: {
454
+ key: REPORT_KEY_ENUM.HOURLY_COMPARISON,
455
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
456
+ reason: 'Read adapters exist but there is no production END_TENANT_DAY writer.',
457
+ },
458
+ [REPORT_KEY_ENUM.PAYMENTS_COMPARISON]: {
459
+ key: REPORT_KEY_ENUM.PAYMENTS_COMPARISON,
460
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
461
+ reason: 'Read adapters exist but there is no production END_TENANT_DAY writer.',
462
+ },
463
+ [REPORT_KEY_ENUM.CREDIT_BILLS]: {
464
+ key: REPORT_KEY_ENUM.CREDIT_BILLS,
465
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
466
+ reason: 'Historical-only ledger; no live read adapter.',
467
+ },
468
+ [REPORT_KEY_ENUM.ITERATIONS]: {
469
+ key: REPORT_KEY_ENUM.ITERATIONS,
470
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
471
+ reason: 'Shared history read, not a report family.',
472
+ },
473
+ [REPORT_KEY_ENUM.SUMMARY]: {
474
+ key: REPORT_KEY_ENUM.SUMMARY,
475
+ status: REPORT_DEFINITION_STATUS.PLANNED,
476
+ reason: 'No implementation.',
477
+ },
478
+ [REPORT_KEY_ENUM.X_REPORT]: {
479
+ key: REPORT_KEY_ENUM.X_REPORT,
480
+ status: REPORT_DEFINITION_STATUS.PLANNED,
481
+ reason: 'No implementation.',
482
+ },
483
+ [REPORT_KEY_ENUM.Z_REPORT]: {
484
+ key: REPORT_KEY_ENUM.Z_REPORT,
485
+ status: REPORT_DEFINITION_STATUS.PLANNED,
486
+ reason: 'No implementation.',
487
+ },
488
+ [REPORT_KEY_ENUM.ITEMS]: {
489
+ key: REPORT_KEY_ENUM.ITEMS,
490
+ status: REPORT_DEFINITION_STATUS.PLANNED,
491
+ reason: 'No implementation.',
492
+ },
493
+ [REPORT_KEY_ENUM.ITEMS_COMPARISON]: {
494
+ key: REPORT_KEY_ENUM.ITEMS_COMPARISON,
495
+ status: REPORT_DEFINITION_STATUS.PLANNED,
496
+ reason: 'No implementation.',
497
+ },
498
+ [REPORT_KEY_ENUM.VOID_ITEMS]: {
499
+ key: REPORT_KEY_ENUM.VOID_ITEMS,
500
+ status: REPORT_DEFINITION_STATUS.PLANNED,
501
+ reason: 'No implementation.',
502
+ },
503
+ [REPORT_KEY_ENUM.REVIEWS_RATINGS]: {
504
+ key: REPORT_KEY_ENUM.REVIEWS_RATINGS,
505
+ status: REPORT_DEFINITION_STATUS.PLANNED,
506
+ reason: 'No implementation.',
507
+ },
508
+ };
@@ -0,0 +1,4 @@
1
+ export * from './definition';
2
+ export * from './registry';
3
+ export * from './validate-report-registry';
4
+ export * from './lifecycle';
@@ -0,0 +1,27 @@
1
+ import { assertMaterializedDocumentSize } from '../../materialized-document-size';
2
+ export function getReportCollectionBudget(definition, kind, collectionName) {
3
+ if (kind === 'report')
4
+ return definition.budgets[definition.report.name] ?? null;
5
+ if (kind === 'entries') {
6
+ if (definition.entries == null)
7
+ return null;
8
+ return definition.budgets[definition.entries.name] ?? null;
9
+ }
10
+ if (collectionName == null)
11
+ return null;
12
+ if (!definition.sideCollections.some((collection) => collection.name === collectionName)) {
13
+ return null;
14
+ }
15
+ return definition.budgets[collectionName] ?? null;
16
+ }
17
+ export function assertReportDocumentBudget(definition, kind, document, options = {}) {
18
+ const budget = getReportCollectionBudget(definition, kind, options.collectionName);
19
+ if (budget == null) {
20
+ throw new Error(`assertReportDocumentBudget: ${definition.key} has no budget for ${kind}${options.collectionName == null ? '' : `:${options.collectionName}`}`);
21
+ }
22
+ assertMaterializedDocumentSize(document, {
23
+ collection: options.collectionName ?? (kind === 'report' ? definition.report.name : definition.entries?.name),
24
+ label: options.label ?? definition.key,
25
+ maxBytes: budget,
26
+ });
27
+ }
@@ -0,0 +1,12 @@
1
+ export const EMPTY_REPORT_CAP_METADATA = {
2
+ cappedCellCount: 0,
3
+ cappedOrderCount: 0,
4
+ exact: true,
5
+ };
6
+ export function mergeReportCapMetadata(left, right) {
7
+ return {
8
+ cappedCellCount: Number(left?.cappedCellCount ?? 0) + Number(right?.cappedCellCount ?? 0),
9
+ cappedOrderCount: Number(left?.cappedOrderCount ?? 0) + Number(right?.cappedOrderCount ?? 0),
10
+ exact: (left?.exact ?? true) && (right?.exact ?? true),
11
+ };
12
+ }
@@ -0,0 +1,121 @@
1
+ import { MATERIALIZED_REPORT_SCOPE_ENUM } from '../../../../constants/MATERIALIZED_REPORTS';
2
+ import { materializedDocumentBsonBytes } from '../../materialized-document-size';
3
+ import { REPORT_ENTRY_STORAGE } from '../definition';
4
+ /**
5
+ * PHASE 2 — generic entry page identity + deterministic #N splitter.
6
+ *
7
+ * The splitter is a generic transcription of the CURRENT Delivery splitter. It
8
+ * is not wired into any writer; the equivalence test runs both implementations
9
+ * over the same compiled Delivery page and requires byte-identical output.
10
+ */
11
+ export const ENTRY_PAGE_ALL = 'all';
12
+ const SUB_PAGE_PATTERN = /^(.*)#(\d+)$/;
13
+ export function isEntryPageScope(scope) {
14
+ return (String(scope) === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR ||
15
+ String(scope) === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE ||
16
+ String(scope) === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK ||
17
+ String(scope) === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR ||
18
+ String(scope) === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH);
19
+ }
20
+ /**
21
+ * `page` value for one entry scope, matching Discounts and Delivery:
22
+ * day/hour scopes are already one day -> `all`; period scopes use the SOURCE day.
23
+ * Reports with `ONE_PER_SCOPE` or `NONE` return null.
24
+ */
25
+ export function resolveEntryPageForScope(definition, scopeContext, sourceLocalDate) {
26
+ if (definition.entryStorage !== REPORT_ENTRY_STORAGE.PAGE_PER_SOURCE_DAY) {
27
+ return null;
28
+ }
29
+ if (!isEntryPageScope(scopeContext))
30
+ return null;
31
+ const scope = String(scopeContext);
32
+ if (scope === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR || scope === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE) {
33
+ return ENTRY_PAGE_ALL;
34
+ }
35
+ return typeof sourceLocalDate === 'string' && sourceLocalDate !== '' ? sourceLocalDate : null;
36
+ }
37
+ export function entryPageBase(page) {
38
+ const text = String(page ?? '');
39
+ const match = SUB_PAGE_PATTERN.exec(text);
40
+ return match == null ? text : match[1];
41
+ }
42
+ export function isEntryPageForSourceDay(definition, scopeContext, page, sourceLocalDate) {
43
+ const base = resolveEntryPageForScope(definition, scopeContext, sourceLocalDate);
44
+ return base != null && entryPageBase(page) === base;
45
+ }
46
+ export function buildEntrySubPage(basePage, index) {
47
+ return `${basePage}#${Math.max(0, Math.floor(index))}`;
48
+ }
49
+ /**
50
+ * Splits one oversized entry page into deterministic `page#0`, `page#1`, ...
51
+ * chunks. A page that fits keeps its original identity.
52
+ */
53
+ export function splitEntryPage(spec) {
54
+ const { document, maxBytes } = spec;
55
+ if (document == null)
56
+ return [];
57
+ if (materializedDocumentBsonBytes(document) <= maxBytes)
58
+ return [document];
59
+ const sections = spec.sectionsOf(document);
60
+ if (sections == null)
61
+ return [document];
62
+ const basePage = entryPageBase(spec.pageOf(document));
63
+ const baseDoc = spec.rebuild(document, basePage, {});
64
+ const envelopeBytes = materializedDocumentBsonBytes(baseDoc);
65
+ const chunks = [];
66
+ let current = {};
67
+ let currentBytes = envelopeBytes;
68
+ let currentRows = 0;
69
+ const flush = () => {
70
+ if (currentRows > 0)
71
+ chunks.push(current);
72
+ current = {};
73
+ currentBytes = envelopeBytes;
74
+ currentRows = 0;
75
+ };
76
+ for (const key of Object.keys(sections)) {
77
+ for (const row of sections[key]?.rows ?? []) {
78
+ const rowBytes = materializedDocumentBsonBytes(row) + key.length + 24;
79
+ if (currentRows > 0 && currentBytes + rowBytes > maxBytes - 512)
80
+ flush();
81
+ if (current[key] == null)
82
+ current[key] = { rows: [] };
83
+ current[key].rows.push(row);
84
+ currentBytes += rowBytes;
85
+ currentRows += 1;
86
+ if (currentBytes > maxBytes) {
87
+ throw new Error(`Entry page ${spec.scopeLabel?.(document) ?? ''}:${basePage} ` +
88
+ 'cannot split below the budget (one row is too large)');
89
+ }
90
+ }
91
+ }
92
+ flush();
93
+ if (chunks.length <= 1) {
94
+ const allRows = [];
95
+ for (const key of Object.keys(sections)) {
96
+ for (const row of sections[key]?.rows ?? [])
97
+ allRows.push({ key, row });
98
+ }
99
+ if (allRows.length < 2) {
100
+ throw new Error(`Entry page ${spec.scopeLabel?.(document) ?? ''}:${basePage} ` + 'is over budget and has no splittable row');
101
+ }
102
+ const mid = Math.ceil(allRows.length / 2);
103
+ const toChunk = (rows) => {
104
+ const chunk = {};
105
+ for (const { key, row } of rows) {
106
+ if (chunk[key] == null)
107
+ chunk[key] = { rows: [] };
108
+ chunk[key].rows.push(row);
109
+ }
110
+ return chunk;
111
+ };
112
+ chunks.push(toChunk(allRows.slice(0, mid)), toChunk(allRows.slice(mid)));
113
+ }
114
+ return chunks.map((chunk, index) => {
115
+ const page = spec.rebuild(document, buildEntrySubPage(basePage, index), chunk);
116
+ if (materializedDocumentBsonBytes(page) > maxBytes) {
117
+ throw new Error(`Entry sub-page ${spec.scopeLabel?.(document) ?? ''}:${spec.pageOf(page)} ` + 'exceeds the entry-page budget');
118
+ }
119
+ return page;
120
+ });
121
+ }