@managesome/eposmatic-toolkit 0.4.27 → 0.4.29

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 (51) hide show
  1. package/esm/helpers/materialized-reports/index.js +1 -0
  2. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +49 -20
  3. package/esm/helpers/materialized-reports/materialized-day-input-signature.js +103 -0
  4. package/esm/helpers/materialized-reports/materialized-discount-close-day-helpers.js +63 -2
  5. package/esm/helpers/materialized-reports/materialized-discount-compile-helpers.js +18 -0
  6. package/esm/helpers/materialized-reports/scope-helpers.js +27 -0
  7. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +122 -9
  8. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +24 -2
  9. package/esm/schemas/models/materialized_credit_bills.js +8 -0
  10. package/esm/schemas/models/materialized_tenant_discount_reports.js +9 -0
  11. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
  12. package/esm/schemas/models/tenant_active_jobs.js +8 -0
  13. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  14. package/lib/helpers/materialized-reports/index.js +1 -0
  15. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +28 -2
  16. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +50 -20
  17. package/lib/helpers/materialized-reports/materialized-day-input-signature.d.ts +66 -0
  18. package/lib/helpers/materialized-reports/materialized-day-input-signature.js +108 -0
  19. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.d.ts +20 -1
  20. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.js +63 -2
  21. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.js +18 -0
  22. package/lib/helpers/materialized-reports/scope-helpers.d.ts +22 -0
  23. package/lib/helpers/materialized-reports/scope-helpers.js +28 -0
  24. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +41 -3
  25. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +120 -7
  26. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +4 -1
  27. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +24 -2
  28. package/lib/schemas/models/materialized_credit_bills.d.ts +3 -0
  29. package/lib/schemas/models/materialized_credit_bills.js +8 -0
  30. package/lib/schemas/models/materialized_tenant_discount_reports.d.ts +3 -0
  31. package/lib/schemas/models/materialized_tenant_discount_reports.js +9 -0
  32. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +3 -0
  33. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
  34. package/lib/schemas/models/tenant_active_jobs.d.ts +3 -0
  35. package/lib/schemas/models/tenant_active_jobs.js +8 -0
  36. package/lib/schemas/types/materialized_credit_bills.d.ts +6 -0
  37. package/lib/schemas/types/materialized_tenant_discount_reports.d.ts +6 -0
  38. package/lib/schemas/types/materialized_tenant_reports_iterations.d.ts +9 -0
  39. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +14 -0
  40. package/lib/schemas/types/tenant_active_jobs.d.ts +8 -0
  41. package/lib/tests/materialized-reports/materialized-day-input-signature.test.d.ts +1 -0
  42. package/lib/tests/materialized-reports/materialized-day-input-signature.test.js +81 -0
  43. package/lib/tests/materialized-reports/materialized-discount-close-day.test.js +89 -0
  44. package/lib/tests/materialized-reports/materialized-discount-scenarios.test.d.ts +1 -0
  45. package/lib/tests/materialized-reports/materialized-discount-scenarios.test.js +676 -0
  46. package/lib/tests/materialized-reports/materialized-discount-sources.test.js +134 -0
  47. package/lib/tests/materialized-reports/real-discount-orders.test.d.ts +1 -0
  48. package/lib/tests/materialized-reports/real-discount-orders.test.js +110 -0
  49. package/lib/tests/materialized-reports/tenant-discount-source-formatter.test.js +11 -2
  50. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +162 -0
  51. package/package.json +1 -1
@@ -3,6 +3,7 @@ import { PAYMENT_STATUS_ENUM, PAYMENT_TYPE_ENUM, REPORT_SALE_TYPE_ENUM } from '.
3
3
  import { MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX, SALES_OVERVIEW_KEY_FILTERS, } from '../../constants/MATERIALIZED_REPORTS';
4
4
  import { MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME, MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION, MaterializedTenantSalesOverviewReportSchema, } from '../../schemas/models/materialized_tenant_sales_overview_reports';
5
5
  import { buildMaterializedReportKey } from './key-helpers';
6
+ import { buildMaterializedDayInputSignature, } from './materialized-day-input-signature';
6
7
  import { buildCreditBillEventCandidatesFromOrder, buildCreditBillIssuedCandidatesFromOrder, isMaterializedCreditBillPayment, resolveOrderLocalHour, resolveReceivedLocalHour, } from './materialized-credit-bills-helpers';
7
8
  import { getDayIndexFromLocalDate, getMaterializedHourScopeField, getMaterializedPeriodScopeFields, parseMaterializedLocalDate, } from './scope-helpers';
8
9
  /* ------------------------------------------------------------------------ */
@@ -506,13 +507,26 @@ export function convertOrdersToMaterializedTenantSalesOverviewReports(localDate,
506
507
  // `source_watermark` = max `order.updatedAt` folded in; a day with no
507
508
  // orders folds nothing → epoch. Stable across recompiles, so the
508
509
  // watermark guard skips unchanged (order-less) days instead of churning.
509
- const watermark = tenantOrders.reduce((latest, order) => {
510
+ //
511
+ // `source_input_signature` is the SET-shaped companion: the watermark only
512
+ // advances, so a delete / move that removes the maximum-`updatedAt` order
513
+ // would leave the incoming watermark LOWER than the stored one and the
514
+ // guard would skip the correction. The digest changes with the input set,
515
+ // so the close is still applied. Both are computed from the SAME
516
+ // `tenantOrders` array the compile consumed.
517
+ // Both change-detection signals describe the orders this day ACTUALLY
518
+ // materializes: a deleted order must never keep the day "fresh" (or
519
+ // contribute a watermark the remaining orders cannot reproduce).
520
+ const consideredOrders = tenantOrders.filter((order) => order.is_deleted === false);
521
+ const watermark = consideredOrders.reduce((latest, order) => {
510
522
  const updatedAt = new Date(order.updatedAt ?? now);
511
523
  return updatedAt.getTime() > latest.getTime() ? updatedAt : latest;
512
524
  }, new Date(0));
525
+ const sourceInputSignature = buildMaterializedDayInputSignature(consideredOrders) ?? undefined;
513
526
  for (const { doc, metrics } of [...periodDocs, ...hourDocs.values()]) {
514
527
  doc.sale_type_metrics = finalizeMetrics(metrics);
515
528
  doc.source_watermark = watermark;
529
+ doc.source_input_signature = sourceInputSignature;
516
530
  materializedReports.push(doc);
517
531
  }
518
532
  }
@@ -736,7 +750,10 @@ export function subtractMaterializedTenantSalesOverviewReports(minuend, subtrahe
736
750
  * so replays stay churn-free;
737
751
  * 4. `source_watermark` advances to the max of the existing and the incoming
738
752
  * (`replacement` / `additions`) watermarks — monotonic, never regressed
739
- * (rollbacks / replays keep the previously folded maximum).
753
+ * (rollbacks / replays keep the previously folded maximum);
754
+ * 5. `source_input_signature` follows a `replacement` (the fresh day compile)
755
+ * and is KEPT on period accumulates — a period's payload is a running sum,
756
+ * not one day's input set.
740
757
  *
741
758
  * Returns a new JSON report; the input is not mutated.
742
759
  */
@@ -794,6 +811,11 @@ export function updateMaterializedTenantSalesOverviewReport(existing, updates, o
794
811
  // Reconcile artifacts: a fully-subtracted key is pruned so accumulated
795
812
  // period documents keep the same key set as day / hour reads.
796
813
  sale_type_metrics: pruneZeroReportKeys(finalizeMetrics(metrics)),
814
+ // The day-input digest travels with a REPLACEMENT write (the freshly
815
+ // compiled day/hour document) so the next close can compare it. Period
816
+ // accumulates keep the stored value: their payload is a running sum, not
817
+ // one day's input set.
818
+ source_input_signature: updates.replacement?.source_input_signature ?? existing.source_input_signature,
797
819
  // Version metric writes AND ledger-changing received-payment patches (both
798
820
  // append a history row via the caller). No-op patches bump nothing, so
799
821
  // replays stay churn-free.
@@ -201,6 +201,14 @@ export const MaterializedTenantCreditBillsReportSchema = new Schema({
201
201
  type: Schema.Types.Date,
202
202
  required: true,
203
203
  },
204
+ // Day-input digest (`v1:<count>:<hash>`) — set-shaped change detection
205
+ // for the credit ledger, mirroring the sales-overview reports. A deleted /
206
+ // moved order must remove its bill even when the watermark regresses.
207
+ source_input_signature: {
208
+ type: String,
209
+ required: false,
210
+ default: undefined,
211
+ },
204
212
  computed_at: {
205
213
  type: Schema.Types.Date,
206
214
  required: true,
@@ -207,6 +207,15 @@ export const MaterializedTenantDiscountReportSchema = new Schema({
207
207
  type: Schema.Types.Date,
208
208
  required: true,
209
209
  },
210
+ // Day-input digest (`v1:<count>:<hash>`) — set-shaped change detection
211
+ // for the discount counters, mirroring the sales-overview reports. A
212
+ // deleted / moved order must remove its discount even when the watermark
213
+ // regresses.
214
+ source_input_signature: {
215
+ type: String,
216
+ required: false,
217
+ default: undefined,
218
+ },
210
219
  computed_at: {
211
220
  type: Schema.Types.Date,
212
221
  required: true,
@@ -264,6 +264,15 @@ export const MaterializedTenantSalesOverviewReportSchema = new Schema({
264
264
  type: Schema.Types.Date,
265
265
  required: true,
266
266
  },
267
+ // Day-input digest (`v1:<count>:<hash>`) — the SET-shaped half of change
268
+ // detection. A delete / move can lower the incoming watermark; the digest
269
+ // changes instead, so the close still performs the corrective writes.
270
+ // Optional: documents written before it existed are rewritten once.
271
+ source_input_signature: {
272
+ type: String,
273
+ required: false,
274
+ default: undefined,
275
+ },
267
276
  computed_at: {
268
277
  type: Schema.Types.Date,
269
278
  required: true,
@@ -27,6 +27,14 @@ export const TenantActiveJobSchema = new Schema({
27
27
  enum: ALL_TENANT_ACTIVE_JOBS_NAMES,
28
28
  default: null,
29
29
  },
30
+ // Fencing token of the current owner — fresh per acquisition. Updates,
31
+ // completion and failure filter on it so a stale owner cannot touch the
32
+ // job after a takeover. `null` when the job is free.
33
+ lease_id: {
34
+ type: String,
35
+ required: false,
36
+ default: null,
37
+ },
30
38
  failed_jobs: {
31
39
  type: [String],
32
40
  enum: ALL_TENANT_ACTIVE_JOBS_NAMES,
@@ -18,6 +18,7 @@ export * from './materialized-delivery-accumulator-helpers';
18
18
  export * from './materialized-delivery-compile-helpers';
19
19
  export * from './materialized-delivery-classification-helpers';
20
20
  export * from './materialized-delivery-close-day-helpers';
21
+ export * from './materialized-day-input-signature';
21
22
  export * from './materialized-cash-classification-helpers';
22
23
  export * from './materialized-cash-close-day-helpers';
23
24
  export * from './materialized-cash-compile-helpers';
@@ -34,6 +34,7 @@ __exportStar(require("./materialized-delivery-accumulator-helpers"), exports);
34
34
  __exportStar(require("./materialized-delivery-compile-helpers"), exports);
35
35
  __exportStar(require("./materialized-delivery-classification-helpers"), exports);
36
36
  __exportStar(require("./materialized-delivery-close-day-helpers"), exports);
37
+ __exportStar(require("./materialized-day-input-signature"), exports);
37
38
  __exportStar(require("./materialized-cash-classification-helpers"), exports);
38
39
  __exportStar(require("./materialized-cash-close-day-helpers"), exports);
39
40
  __exportStar(require("./materialized-cash-compile-helpers"), exports);
@@ -1,6 +1,6 @@
1
1
  import { MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM } from '../../constants/MATERIALIZED_REPORTS';
2
2
  import { IOrder, IOrderPayment } from '../../schemas';
3
- import { IMaterializedCreditBillIssuedEntry, IMaterializedCreditBillReceivedEntry, IMaterializedTenantCreditBillsReport } from '../../schemas/types/materialized_credit_bills';
3
+ import { IMaterializedCreditBillIssuedEntry, IMaterializedCreditBillKeySection, IMaterializedCreditBillReceivedEntry, IMaterializedTenantCreditBillsReport } from '../../schemas/types/materialized_credit_bills';
4
4
  import { IGetMaterializedReportScopeGroup } from '../types/materialized-reports-apis';
5
5
  /**
6
6
  * The shared credit-bill ledger (`materialized_tenant_credit_bills`) —
@@ -174,7 +174,28 @@ export interface IBuildMaterializedCreditBillDayReportsInput {
174
174
  localDate: string;
175
175
  resolution: ICreditBillDayResolution;
176
176
  computedAt: Date;
177
+ /**
178
+ * Day-input digest (`buildMaterializedDayInputSignature`) of the orders the
179
+ * resolution was compiled from — the SET-shaped half of change detection
180
+ * (a delete / move must correct the ledger even when the watermark
181
+ * regresses). Optional so existing callers keep working; a document without
182
+ * one is re-materialized by the guard on its next close.
183
+ */
184
+ sourceInputSignature?: string | null;
177
185
  }
186
+ /**
187
+ * Folds `source` sections INTO `target` (mutating it), identity-matched:
188
+ * an ISSUED entry is one `(order_id, payment_id)` bill; a RECEIVED entry is one
189
+ * `(order_id, payment_id, event_local_date)` collection event. A source entry
190
+ * REPLACES its target counterpart (fresh wins), so re-applying the same day is
191
+ * idempotent.
192
+ *
193
+ * Exported because the close-day plan uses the SAME merge when it rebuilds a
194
+ * MISSING period document from the stored day documents (a deleted period
195
+ * document must not be recreated from the closing day alone; see
196
+ * `buildTenantSalesOverviewCloseDayPlan`'s period repair).
197
+ */
198
+ export declare function mergeMaterializedCreditBillSections(target: Record<string, IMaterializedCreditBillKeySection>, source: Record<string, IMaterializedCreditBillKeySection> | null | undefined): void;
178
199
  /**
179
200
  * Materializes ONE day's credit documents from its resolution — the
180
201
  * month-capped scope set (`MATERIALIZED_CREDIT_BILLS_SCOPES`): one document per
@@ -208,7 +229,12 @@ export interface IMaterializedCreditBillScopeRef {
208
229
  scope_context: MATERIALIZED_REPORT_SCOPE_ENUM;
209
230
  scope_field: string;
210
231
  }
211
- /** `Writes the watermarks / schema / key-filter grammar allow a write?` (mirrors the sales-report guard). */
232
+ /**
233
+ * `Writes the watermarks / day-input signature / schema / key-filter grammar
234
+ * allow a write?` (mirrors the sales-report guard). The signature is checked
235
+ * FIRST so a deleted / moved order still corrects the ledger when the incoming
236
+ * watermark regressed.
237
+ */
212
238
  export declare const needsMaterializedCreditBillsReportWrite: (existing: IMaterializedTenantCreditBillsReport | null | undefined, incoming: IMaterializedTenantCreditBillsReport) => boolean;
213
239
  /**
214
240
  * The day-close fetch plan: every scope document one compiled day may touch —
@@ -7,6 +7,7 @@ exports.needsMaterializedCreditBillsReportWrite = exports.toMaterializedHourLabe
7
7
  exports.buildCreditBillIssuedCandidatesFromOrder = buildCreditBillIssuedCandidatesFromOrder;
8
8
  exports.buildCreditBillEventCandidatesFromOrder = buildCreditBillEventCandidatesFromOrder;
9
9
  exports.resolveCreditBillDay = resolveCreditBillDay;
10
+ exports.mergeMaterializedCreditBillSections = mergeMaterializedCreditBillSections;
10
11
  exports.buildMaterializedCreditBillDayReports = buildMaterializedCreditBillDayReports;
11
12
  exports.updateMaterializedCreditBillsReport = updateMaterializedCreditBillsReport;
12
13
  exports.getMaterializedCreditBillScopeRefsForDay = getMaterializedCreditBillScopeRefsForDay;
@@ -20,6 +21,7 @@ const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
20
21
  const materialized_credit_bills_1 = require("../../schemas/models/materialized_credit_bills");
21
22
  const time_helpers_1 = require("../utils/time-helpers");
22
23
  const key_helpers_1 = require("./key-helpers");
24
+ const materialized_day_input_signature_1 = require("./materialized-day-input-signature");
23
25
  const scope_helpers_1 = require("./scope-helpers");
24
26
  /**
25
27
  * The shared credit-bill ledger (`materialized_tenant_credit_bills`) —
@@ -361,6 +363,39 @@ function resolveCreditBillDay(input) {
361
363
  }
362
364
  const emptySection = () => ({ issued: [], received: [] });
363
365
  const sectionFor = (map, key) => map[key] ?? (map[key] = emptySection());
366
+ /**
367
+ * Folds `source` sections INTO `target` (mutating it), identity-matched:
368
+ * an ISSUED entry is one `(order_id, payment_id)` bill; a RECEIVED entry is one
369
+ * `(order_id, payment_id, event_local_date)` collection event. A source entry
370
+ * REPLACES its target counterpart (fresh wins), so re-applying the same day is
371
+ * idempotent.
372
+ *
373
+ * Exported because the close-day plan uses the SAME merge when it rebuilds a
374
+ * MISSING period document from the stored day documents (a deleted period
375
+ * document must not be recreated from the closing day alone; see
376
+ * `buildTenantSalesOverviewCloseDayPlan`'s period repair).
377
+ */
378
+ function mergeMaterializedCreditBillSections(target, source) {
379
+ for (const [key, section] of Object.entries(source ?? {})) {
380
+ const bucket = target[key] ?? (target[key] = emptySection());
381
+ for (const entry of section?.issued ?? []) {
382
+ const identity = creditBillIdentityKey(entry.order_id, entry.payment_id);
383
+ const index = bucket.issued.findIndex((current) => creditBillIdentityKey(current.order_id, current.payment_id) === identity);
384
+ if (index >= 0)
385
+ bucket.issued[index] = entry;
386
+ else
387
+ bucket.issued.push(entry);
388
+ }
389
+ for (const entry of section?.received ?? []) {
390
+ const identity = `${creditBillIdentityKey(entry.order_id, entry.payment_id)}|${entry.event_local_date}`;
391
+ const index = bucket.received.findIndex((current) => `${creditBillIdentityKey(current.order_id, current.payment_id)}|${current.event_local_date}` === identity);
392
+ if (index >= 0)
393
+ bucket.received[index] = entry;
394
+ else
395
+ bucket.received.push(entry);
396
+ }
397
+ }
398
+ }
364
399
  /**
365
400
  * Materializes ONE day's credit documents from its resolution — the
366
401
  * month-capped scope set (`MATERIALIZED_CREDIT_BILLS_SCOPES`): one document per
@@ -371,6 +406,7 @@ function buildMaterializedCreditBillDayReports(input) {
371
406
  if (input == null)
372
407
  return null;
373
408
  const { tenantId, brandId, localDate, resolution, computedAt } = input;
409
+ const sourceInputSignature = input.sourceInputSignature ?? undefined;
374
410
  const periodFields = (0, scope_helpers_1.getMaterializedPeriodScopeFields)(localDate);
375
411
  if (periodFields == null)
376
412
  return null;
@@ -440,6 +476,7 @@ function buildMaterializedCreditBillDayReports(input) {
440
476
  iteration: 1,
441
477
  schema_version: materialized_credit_bills_1.MATERIALIZED_CREDIT_BILLS_SCHEMA_VERSION,
442
478
  source_watermark: sourceWatermark,
479
+ source_input_signature: sourceInputSignature,
443
480
  computed_at: computedAt,
444
481
  createdAt: computedAt,
445
482
  updatedAt: computedAt,
@@ -540,25 +577,7 @@ function updateMaterializedCreditBillsReport(existing, updates, options = {}) {
540
577
  }
541
578
  }
542
579
  for (const delta of updates.additions ?? []) {
543
- for (const [key, section] of Object.entries(toMutableSections(delta.credit_bills))) {
544
- const target = sections[key] ?? (sections[key] = emptySection());
545
- for (const entry of section.issued) {
546
- const identity = creditBillIdentityKey(entry.order_id, entry.payment_id);
547
- const index = target.issued.findIndex((current) => creditBillIdentityKey(current.order_id, current.payment_id) === identity);
548
- if (index >= 0)
549
- target.issued[index] = entry;
550
- else
551
- target.issued.push(entry);
552
- }
553
- for (const entry of section.received) {
554
- const identity = `${creditBillIdentityKey(entry.order_id, entry.payment_id)}|${entry.event_local_date}`;
555
- const index = target.received.findIndex((current) => `${creditBillIdentityKey(current.order_id, current.payment_id)}|${current.event_local_date}` === identity);
556
- if (index >= 0)
557
- target.received[index] = entry;
558
- else
559
- target.received.push(entry);
560
- }
561
- }
580
+ mergeMaterializedCreditBillSections(sections, toMutableSections(delta.credit_bills));
562
581
  }
563
582
  for (const delta of updates.additions ?? []) {
564
583
  sourceWatermark = maxDate(sourceWatermark, delta.source_watermark) ?? sourceWatermark;
@@ -591,6 +610,9 @@ function updateMaterializedCreditBillsReport(existing, updates, options = {}) {
591
610
  ...existing,
592
611
  credit_bills: pruned,
593
612
  iteration: (existing.iteration ?? 1) + (changed || ledgerPatched ? 1 : 0),
613
+ // A REPLACEMENT carries the freshly compiled day digest; period folds keep
614
+ // the stored value (their payload is a running ledger, not one day's input).
615
+ source_input_signature: updates.replacement?.source_input_signature ?? existing.source_input_signature,
594
616
  source_watermark: sourceWatermark,
595
617
  computed_at: computedAt,
596
618
  updatedAt: computedAt,
@@ -616,7 +638,12 @@ const creditPeriodRefs = (localDate) => {
616
638
  },
617
639
  ];
618
640
  };
619
- /** `Writes the watermarks / schema / key-filter grammar allow a write?` (mirrors the sales-report guard). */
641
+ /**
642
+ * `Writes the watermarks / day-input signature / schema / key-filter grammar
643
+ * allow a write?` (mirrors the sales-report guard). The signature is checked
644
+ * FIRST so a deleted / moved order still corrects the ledger when the incoming
645
+ * watermark regressed.
646
+ */
620
647
  const needsMaterializedCreditBillsReportWrite = (existing, incoming) => {
621
648
  if (existing == null)
622
649
  return true;
@@ -625,6 +652,9 @@ const needsMaterializedCreditBillsReportWrite = (existing, incoming) => {
625
652
  if (JSON.stringify(existing.sale_type_key_filters ?? []) !== JSON.stringify(incoming.sale_type_key_filters ?? [])) {
626
653
  return true;
627
654
  }
655
+ if ((0, materialized_day_input_signature_1.materializedDayInputSignatureChanged)(existing.source_input_signature, incoming.source_input_signature)) {
656
+ return true;
657
+ }
628
658
  return new Date(incoming.source_watermark).getTime() > new Date(existing.source_watermark).getTime();
629
659
  };
630
660
  exports.needsMaterializedCreditBillsReportWrite = needsMaterializedCreditBillsReportWrite;
@@ -0,0 +1,66 @@
1
+ import { IOrder } from '../../schemas/types/orders';
2
+ /**
3
+ * Day-input SIGNATURE — the change-detection token of a materialized day.
4
+ *
5
+ * ## Why a watermark alone is not enough
6
+ *
7
+ * Every report document stores `source_watermark` = the MAX `orders.updatedAt`
8
+ * folded into it, and the close-day plans skip a document when the incoming
9
+ * watermark is not NEWER than the stored one. That is sound for an UPDATE of an
10
+ * order (its `updatedAt` advances), but it is blind to the order set SHRINKING:
11
+ *
12
+ * - delete the order that carried the maximum `updatedAt`, then re-close the
13
+ * day → the incoming max is LOWER than the stored watermark, the guard
14
+ * reports "nothing new", and the deleted order stays in every report
15
+ * (date/hour/period/credit/discount) forever;
16
+ * - move that order to another `localDate` → same regression on the old day,
17
+ * so the old day keeps a sale it no longer owns.
18
+ *
19
+ * The fix is a SECOND, set-shaped signal: a deterministic digest of the exact
20
+ * order identities (and their versions) the day was compiled from. A delete or
21
+ * a move changes the digest even when the watermark regresses, so the guard can
22
+ * trigger the corrective writes. A re-close of the SAME input reproduces the
23
+ * same digest, so the no-churn skip is preserved.
24
+ *
25
+ * ## Shape
26
+ *
27
+ * `v1:<count>:<hash>` where
28
+ * - `count` is the number of orders in the input (cheap first check);
29
+ * - `hash` is two independent 32-bit FNV-1a passes over the sorted
30
+ * `id|updatedAt` lines, emitted as 16 hex chars (a ~64-bit digest).
31
+ *
32
+ * The leading `v1:` version tag makes the value a non-numeric string, which
33
+ * keeps it outside the integer-only storage contract's numeric-string rule; a
34
+ * future algorithm change must bump the tag so old documents are re-materialized
35
+ * exactly once instead of being silently compared with a different digest.
36
+ *
37
+ * The digest is NOT a security primitive — it detects accidental divergence,
38
+ * and a full re-close always repairs the document regardless.
39
+ */
40
+ /** Version tag of the digest algorithm; bump when the line format changes. */
41
+ export declare const MATERIALIZED_DAY_INPUT_SIGNATURE_VERSION = "v1";
42
+ /**
43
+ * Builds the day-input signature for the orders a materializer compiled.
44
+ *
45
+ * The caller passes the SAME array the compile used (and the same tenant
46
+ * filter); the digest is order-independent (lines are sorted) and idempotent
47
+ * (identical input → identical value). An empty input yields the stable
48
+ * `v1:0:<hash of ''>` value, which is deliberately DIFFERENT from "no stored
49
+ * signature" (`undefined`) — a legacy document with no signature is therefore
50
+ * rewritten once, and an order-less day keeps skipping on later re-closes.
51
+ *
52
+ * Returns `null` (never throws) when the input is not an array.
53
+ */
54
+ export declare function buildMaterializedDayInputSignature(orders: readonly IOrder[] | null | undefined): string | null;
55
+ /**
56
+ * Does a stored / incoming signature pair require a write?
57
+ *
58
+ * - BOTH missing → `false`: neither side describes an input set (legacy
59
+ * fixtures / documents), so the watermark guard decides — exactly the
60
+ * pre-signature behaviour;
61
+ * - exactly ONE missing → `true`: a legacy stored document meets a compiled
62
+ * day (or the reverse), so the corrective write happens once;
63
+ * - different values → `true` (the input SET changed, e.g. a delete or move);
64
+ * - identical → `false` (the watermark guard then decides).
65
+ */
66
+ export declare const materializedDayInputSignatureChanged: (stored: string | null | undefined, incoming: string | null | undefined) => boolean;
@@ -0,0 +1,108 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.materializedDayInputSignatureChanged = exports.MATERIALIZED_DAY_INPUT_SIGNATURE_VERSION = void 0;
4
+ exports.buildMaterializedDayInputSignature = buildMaterializedDayInputSignature;
5
+ /**
6
+ * Day-input SIGNATURE — the change-detection token of a materialized day.
7
+ *
8
+ * ## Why a watermark alone is not enough
9
+ *
10
+ * Every report document stores `source_watermark` = the MAX `orders.updatedAt`
11
+ * folded into it, and the close-day plans skip a document when the incoming
12
+ * watermark is not NEWER than the stored one. That is sound for an UPDATE of an
13
+ * order (its `updatedAt` advances), but it is blind to the order set SHRINKING:
14
+ *
15
+ * - delete the order that carried the maximum `updatedAt`, then re-close the
16
+ * day → the incoming max is LOWER than the stored watermark, the guard
17
+ * reports "nothing new", and the deleted order stays in every report
18
+ * (date/hour/period/credit/discount) forever;
19
+ * - move that order to another `localDate` → same regression on the old day,
20
+ * so the old day keeps a sale it no longer owns.
21
+ *
22
+ * The fix is a SECOND, set-shaped signal: a deterministic digest of the exact
23
+ * order identities (and their versions) the day was compiled from. A delete or
24
+ * a move changes the digest even when the watermark regresses, so the guard can
25
+ * trigger the corrective writes. A re-close of the SAME input reproduces the
26
+ * same digest, so the no-churn skip is preserved.
27
+ *
28
+ * ## Shape
29
+ *
30
+ * `v1:<count>:<hash>` where
31
+ * - `count` is the number of orders in the input (cheap first check);
32
+ * - `hash` is two independent 32-bit FNV-1a passes over the sorted
33
+ * `id|updatedAt` lines, emitted as 16 hex chars (a ~64-bit digest).
34
+ *
35
+ * The leading `v1:` version tag makes the value a non-numeric string, which
36
+ * keeps it outside the integer-only storage contract's numeric-string rule; a
37
+ * future algorithm change must bump the tag so old documents are re-materialized
38
+ * exactly once instead of being silently compared with a different digest.
39
+ *
40
+ * The digest is NOT a security primitive — it detects accidental divergence,
41
+ * and a full re-close always repairs the document regardless.
42
+ */
43
+ /** Version tag of the digest algorithm; bump when the line format changes. */
44
+ exports.MATERIALIZED_DAY_INPUT_SIGNATURE_VERSION = 'v1';
45
+ /** One stable line per order: identity + the version that produced its numbers. */
46
+ const signatureLine = (order) => {
47
+ const id = order._id == null ? '' : String(order._id);
48
+ const updatedAt = order.updatedAt == null ? '' : new Date(order.updatedAt).toISOString();
49
+ return `${id}|${updatedAt}`;
50
+ };
51
+ /** Two independent FNV-1a 32-bit passes over `value`, as 16 hex chars. */
52
+ const hashSignatureLines = (value) => {
53
+ let first = 0x811c9dc5;
54
+ let second = 0x01000193 ^ 0x9e3779b9;
55
+ for (let index = 0; index < value.length; index += 1) {
56
+ const code = value.charCodeAt(index);
57
+ first ^= code;
58
+ first = Math.imul(first, 0x01000193) >>> 0;
59
+ second = Math.imul(second ^ code, 0x85ebca6b) >>> 0;
60
+ second = (second ^ (second >>> 13)) >>> 0;
61
+ }
62
+ return `${first.toString(16).padStart(8, '0')}${second.toString(16).padStart(8, '0')}`;
63
+ };
64
+ /**
65
+ * Builds the day-input signature for the orders a materializer compiled.
66
+ *
67
+ * The caller passes the SAME array the compile used (and the same tenant
68
+ * filter); the digest is order-independent (lines are sorted) and idempotent
69
+ * (identical input → identical value). An empty input yields the stable
70
+ * `v1:0:<hash of ''>` value, which is deliberately DIFFERENT from "no stored
71
+ * signature" (`undefined`) — a legacy document with no signature is therefore
72
+ * rewritten once, and an order-less day keeps skipping on later re-closes.
73
+ *
74
+ * Returns `null` (never throws) when the input is not an array.
75
+ */
76
+ function buildMaterializedDayInputSignature(orders) {
77
+ if (!Array.isArray(orders))
78
+ return null;
79
+ const lines = [];
80
+ for (const order of orders) {
81
+ if (order == null)
82
+ continue;
83
+ lines.push(signatureLine(order));
84
+ }
85
+ lines.sort();
86
+ return `${exports.MATERIALIZED_DAY_INPUT_SIGNATURE_VERSION}:${lines.length}:${hashSignatureLines(lines.join('\n'))}`;
87
+ }
88
+ /**
89
+ * Does a stored / incoming signature pair require a write?
90
+ *
91
+ * - BOTH missing → `false`: neither side describes an input set (legacy
92
+ * fixtures / documents), so the watermark guard decides — exactly the
93
+ * pre-signature behaviour;
94
+ * - exactly ONE missing → `true`: a legacy stored document meets a compiled
95
+ * day (or the reverse), so the corrective write happens once;
96
+ * - different values → `true` (the input SET changed, e.g. a delete or move);
97
+ * - identical → `false` (the watermark guard then decides).
98
+ */
99
+ const materializedDayInputSignatureChanged = (stored, incoming) => {
100
+ const storedMissing = typeof stored !== 'string';
101
+ const incomingMissing = typeof incoming !== 'string';
102
+ if (storedMissing && incomingMissing)
103
+ return false;
104
+ if (storedMissing || incomingMissing)
105
+ return true;
106
+ return stored !== incoming;
107
+ };
108
+ exports.materializedDayInputSignatureChanged = materializedDayInputSignatureChanged;
@@ -93,6 +93,18 @@ export interface IBuildTenantDiscountCloseDayPlanInput {
93
93
  * set; without this acknowledgement the plan refuses to guess.
94
94
  */
95
95
  existingEntriesComplete?: boolean;
96
+ /**
97
+ * Stored `localDate` COUNTER documents of the same tenant (the sibling days
98
+ * inside the touched periods, excluding the closing day), used ONLY to
99
+ * rebuild a MISSING period counter document.
100
+ *
101
+ * A period counter document is a running sum. Creating it from the closing
102
+ * day alone would leave every earlier materialized day out of the period
103
+ * while those days' `localDate` documents still exist, so `localMonth` would
104
+ * no longer equal the sum of its days. The plan folds the siblings that
105
+ * belong to the created scope.
106
+ */
107
+ existingPeriodDayDocuments?: IMaterializedTenantDiscountReport[];
96
108
  /** Why this close is applied — stored as every history row's `reason`. */
97
109
  reason: string;
98
110
  /** Force structural writes even when the watermarks are up to date. */
@@ -115,6 +127,11 @@ export interface ITenantDiscountCloseDayPlan {
115
127
  skippedEntryDocuments: IMaterializedTenantDiscountEntries[];
116
128
  /** Period counter docs this close CREATED because they were absent. */
117
129
  createdPeriodDocuments: IMaterializedDiscountScopeRef[];
130
+ /**
131
+ * Stored sibling DAY documents folded into those created period counter
132
+ * documents (see `existingPeriodDayDocuments`). 0 = nothing to repair.
133
+ */
134
+ foldedPeriodDayDocuments: number;
118
135
  }
119
136
  /** Every stored scope one local day's plan needs (date + 3 periods + 24 hours). */
120
137
  export declare function getMaterializedDiscountScopeRefsForDay(localDate: string): IMaterializedDiscountScopeRef[] | null;
@@ -140,7 +157,9 @@ export declare function getMaterializedDiscountPeriodDayScopeFields(localDate: s
140
157
  /**
141
158
  * Watermark guard: does the stored document need a structural write?
142
159
  * `false` (skip) when the incoming `source_watermark` is not newer than the
143
- * stored one and the schema version + key grammar match.
160
+ * stored one, the day-input SIGNATURE is unchanged, and the schema version +
161
+ * key grammar match. The signature catches a deleted / moved order whose
162
+ * removal lowered the incoming watermark.
144
163
  */
145
164
  export declare function needsMaterializedDiscountReportWrite(existing: IMaterializedTenantDiscountReport | null | undefined, incoming: IMaterializedTenantDiscountReport | null | undefined): boolean;
146
165
  /**