@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/reporting/ledger/producer.mjs

@@ -6,6 +6,8 @@ import {
   canonicalJsonV1,
   reportingIsoDurationMillisecondsV1,
   reportingCoverageDenominatorFingerprintV1,
+  reportingScheduleOriginV1,
+  reportingUtcOffsetChangesV1,
   REPORTING_SOURCE_CONTRACT_VERSION_V1,
   validateReportingSourceExecutionV1
 } from "../source/index.mjs";
@@ -42,14 +44,9 @@ function createReportingProducer(options) {
         },
         ...input.supersededAt ? { supersededAt: new Date(instant(input.supersededAt, "supersededAt")).toISOString() } : {}
       };
-      const offering = requiredOffering(offeringById, normalizedInput.offeringId);
-      validateConfigurationAgainstOffering(normalizedInput, offering);
       const existing = (await options.store.listConfigurations(normalizedInput.account.account_id)).filter(
         (value) => value.delivery_config_id === normalizedInput.delivery_config_id
       );
-      if (existing.some((value) => value.delivery_config_version > normalizedInput.delivery_config_version)) {
-        throw new Error("Reporting configuration version cannot regress");
-      }
       const semantic = { ...normalizedInput };
       const semanticFingerprint = prefixedDigest(semantic);
       const predecessorFingerprint = prefixedDigest({ ...input });
@@ -60,6 +57,10 @@ function createReportingProducer(options) {
         }
         return replay;
       }
+      validateConfigurationAgainstOffering(normalizedInput, requiredOffering(offeringById, normalizedInput.offeringId));
+      if (existing.some((value) => value.delivery_config_version > normalizedInput.delivery_config_version)) {
+        throw new Error("Reporting configuration version cannot regress");
+      }
       const installedAt = (/* @__PURE__ */ new Date()).toISOString();
       const configuration = {
         ...normalizedInput,
@@ -112,7 +113,14 @@ function createReportingProducer(options) {
             await reconcileReportingStatusLifecycleV1({
               store: options.store,
               reporting_obligation_id: written.value.reporting_obligation_id,
-              ledgerAsOf: now,
+              // A fallback clock, never a pinned cutoff. `now` is this host's
+              // instant: a host running fast pinned a cutoff ahead of the
+              // database, the watermark was stamped with it, and every
+              // database-timestamped change inside that skew — a revocation,
+              // a receipt — landed behind the watermark and never made the
+              // obligation due again, so a `complete` transition and its
+              // webhook stood over state that had already contradicted it.
+              now: () => new Date(now),
               subscribers: options.subscribers
             });
           }
@@ -138,16 +146,35 @@ function createReportingProducer(options) {
         throw new RangeError(`settlementGraceMilliseconds must not exceed ${MAX_SETTLEMENT_GRACE_MS}`);
       }
       const owner = `reporting-worker-${randomUUID()}`;
-      const counts = { claimed: 0, revisionsCommitted: 0, notReady: 0, failed: 0 };
+      const counts = { claimed: 0, revisionsCommitted: 0, notReady: 0, failed: 0, reconcilesDeferred: 0 };
+      const reconcileQuietly = async (reporting_obligation_id, nowAt) => {
+        try {
+          await reconcileReportingStatusLifecycleV1({
+            store: options.store,
+            reporting_obligation_id,
+            // Fallback clock, not a pin; see planObligations.
+            now: () => nowAt,
+            subscribers: options.subscribers
+          });
+        } catch (error) {
+          if (workerOptions.signal?.aborted) workerOptions.signal.throwIfAborted();
+          if (isLeaseLost(error)) throw error;
+          counts.reconcilesDeferred += 1;
+        }
+      };
       await retryReportingStatusNotificationsV1({
         store: options.store,
-        ledgerAsOf: now().toISOString(),
+        // A fallback, not a pin: a database-backed store uses its own clock,
+        // while a simulated-time driver still gets the instant it is advancing.
+        fallbackLedgerAsOf: now().toISOString(),
         ...workerOptions.account_id ? { account_id: workerOptions.account_id } : {},
         subscribers: options.subscribers
       });
       await reconcileReportingStatusDeadlinesV1({
         store: options.store,
-        ledgerAsOf: now().toISOString(),
+        // A fallback, not a pin: a database-backed store uses its own clock,
+        // while a simulated-time driver still gets the instant it is advancing.
+        fallbackLedgerAsOf: now().toISOString(),
         ...workerOptions.account_id ? { account_id: workerOptions.account_id } : {},
         subscribers: options.subscribers
       });
@@ -185,12 +212,7 @@ function createReportingProducer(options) {
               obligation.state = nextExisting ? "pending" : "terminal";
               obligation.nextAttemptAt = nextExisting ?? nowValue.toISOString();
               await options.store.updateObligation(obligation, lease);
-              await reconcileReportingStatusLifecycleV1({
-                store: options.store,
-                reporting_obligation_id: obligation.reporting_obligation_id,
-                ledgerAsOf: nowValue.toISOString(),
-                subscribers: options.subscribers
-              });
+              await reconcileQuietly(obligation.reporting_obligation_id, nowValue);
               continue;
             }
           }
@@ -217,12 +239,7 @@ function createReportingProducer(options) {
             await options.store.updateObligation(obligation, lease);
             if (result.error.code === "NOT_READY" || result.error.code === "PARTIAL_RESULT") counts.notReady += 1;
             else counts.failed += 1;
-            await reconcileReportingStatusLifecycleV1({
-              store: options.store,
-              reporting_obligation_id: obligation.reporting_obligation_id,
-              ledgerAsOf: nowValue.toISOString(),
-              subscribers: options.subscribers
-            });
+            await reconcileQuietly(obligation.reporting_obligation_id, nowValue);
             continue;
           }
           const manifest = await validateReportingSourceExecutionV1({
@@ -269,12 +286,7 @@ function createReportingProducer(options) {
           obligation.attemptCount += 1;
           await options.store.updateObligation(obligation, lease);
           await options.store.resolveIssue(sourceExecutionIssueId(obligation), nowValue.toISOString());
-          await reconcileReportingStatusLifecycleV1({
-            store: options.store,
-            reporting_obligation_id: obligation.reporting_obligation_id,
-            ledgerAsOf: nowValue.toISOString(),
-            subscribers: options.subscribers
-          });
+          await reconcileQuietly(obligation.reporting_obligation_id, nowValue);
         } catch (error) {
           if (workerOptions.signal?.aborted) workerOptions.signal.throwIfAborted();
           if (isLeaseLost(error)) continue;
@@ -292,12 +304,7 @@ function createReportingProducer(options) {
               lease,
               sourceExecutionIssue(obligation, nowValue.toISOString())
             );
-            await reconcileReportingStatusLifecycleV1({
-              store: options.store,
-              reporting_obligation_id: obligation.reporting_obligation_id,
-              ledgerAsOf: nowValue.toISOString(),
-              subscribers: options.subscribers
-            });
+            await reconcileQuietly(obligation.reporting_obligation_id, nowValue);
           } catch (recoveryError) {
             if (!isLeaseLost(recoveryError)) throw recoveryError;
           }
@@ -308,13 +315,17 @@ function createReportingProducer(options) {
       }
       await retryReportingStatusNotificationsV1({
         store: options.store,
-        ledgerAsOf: now().toISOString(),
+        // A fallback, not a pin: a database-backed store uses its own clock,
+        // while a simulated-time driver still gets the instant it is advancing.
+        fallbackLedgerAsOf: now().toISOString(),
         ...workerOptions.account_id ? { account_id: workerOptions.account_id } : {},
         subscribers: options.subscribers
       });
       await reconcileReportingStatusDeadlinesV1({
         store: options.store,
-        ledgerAsOf: now().toISOString(),
+        // A fallback, not a pin: a database-backed store uses its own clock,
+        // while a simulated-time driver still gets the instant it is advancing.
+        fallbackLedgerAsOf: now().toISOString(),
         ...workerOptions.account_id ? { account_id: workerOptions.account_id } : {},
         subscribers: options.subscribers
       });
@@ -580,7 +591,7 @@ function buildRevision(obligation, manifestReference, manifest, rows, previous)
     ...previous.at(-1) ? { supersedes_reporting_revision_id: previous.at(-1).reporting_revision_id } : {},
     row_count: rows.length,
     control_totals: controlTotals,
-    ...obligation.feedPurpose === "billing" ? {
+    ...obligation.canonicalization ? {
       canonical_content_digest: {
         algorithm: "sha256",
         value: canonicalRowsSha256(rows, obligation.canonicalization.primaryKeys),
@@ -635,6 +646,9 @@ function validateManifestFinalityForObligation(obligation, manifest) {
     throw new Error("Authoritative source evidence predates the pinned contractual cutoff");
   }
 }
+function reportingCanonicalAdjustmentSha256V1(wireAdjustmentWithoutDigest) {
+  return createHash("sha256").update(canonicalize(wireAdjustmentWithoutDigest), "utf8").digest("hex");
+}
 function canonicalRowsSha256(rows, primaryKeys) {
   const encoded = rows.map((row) => {
     const keyValues = primaryKeys.map((key) => {
@@ -691,6 +705,22 @@ function buildAdjustment(obligation, official, manifestReference, manifest, rows
       }
     ] : [];
   });
+  const wireAdjustmentWithoutDigest = {
+    reporting_adjustment_id: adjustmentId,
+    adjusts_reporting_revision_id: official.reporting_revision_id,
+    reason_code: "source_correction",
+    accounting_period: { start: obligation.period.start, end: obligation.period.end },
+    control_total_deltas: [
+      {
+        name: "row_count",
+        value: String(rows.length - effectiveRowCount(official.binding.rowCount, previous)),
+        value_type: "integer"
+      },
+      ...controlTotalDeltas
+    ],
+    correction_observed_at: manifest.period.observedAt,
+    created_at: createdAt
+  };
   return {
     reporting_adjustment_id: adjustmentId,
     reporting_obligation_id: obligation.reporting_obligation_id,
@@ -704,21 +734,17 @@ function buildAdjustment(obligation, official, manifestReference, manifest, rows
     dataThrough: manifest.period.dataThrough,
     sourceReadCutoffAt: manifest.period.sourceReadCutoffAt,
     createdAt,
+    // `canonical_adjustment_sha256` is optional in RC3 and exists so Reconciled
+    // Billing consumers can recompute the digest before accepting or rejecting
+    // an adjustment. Emitting it unconditionally changed the wire content — and
+    // therefore `adjustmentIdentityFingerprint` — for every Core adopter,
+    // including delivery-only feeds that never read it. Gate it on the same
+    // pinned canonicalization contract that gates the revision's
+    // `canonical_content_digest`, so obligations without one keep byte-identical
+    // output across the upgrade.
     wireAdjustment: ReportingAdjustmentSchema.parse({
-      reporting_adjustment_id: adjustmentId,
-      adjusts_reporting_revision_id: official.reporting_revision_id,
-      reason_code: "source_correction",
-      accounting_period: { start: obligation.period.start, end: obligation.period.end },
-      control_total_deltas: [
-        {
-          name: "row_count",
-          value: String(rows.length - effectiveRowCount(official.binding.rowCount, previous)),
-          value_type: "integer"
-        },
-        ...controlTotalDeltas
-      ],
-      correction_observed_at: manifest.period.observedAt,
-      created_at: createdAt
+      ...wireAdjustmentWithoutDigest,
+      ...obligation.canonicalization ? { canonical_adjustment_sha256: reportingCanonicalAdjustmentSha256V1(wireAdjustmentWithoutDigest) } : {}
     })
   };
 }
@@ -887,6 +913,66 @@ function assertSupportedReportingAuthoritativeParty(configuration) {
 function boundedDiagnostic(value) {
   return String(value).replace(/[\r\n\t]+/g, " ").slice(0, 64);
 }
+const OFFSET_HORIZON_MILLISECONDS = 400 * 864e5;
+const MAX_OFFSET_SCAN_MILLISECONDS = 100 * 365 * 864e5;
+function identityDurationMilliseconds(value) {
+  try {
+    return reportingIsoDurationMillisecondsV1(value);
+  } catch {
+    return void 0;
+  }
+}
+function assertScheduleIdentityMatchesBoundaries(schedule, sourceTimezone, requiredFinality) {
+  if (schedule.periodDuration !== void 0) {
+    if (identityDurationMilliseconds(schedule.periodDuration) !== schedule.periodMilliseconds) {
+      throw new Error("Reporting periodDuration does not describe the configured period boundaries");
+    }
+  }
+  if (schedule.deliverySlaDuration !== void 0) {
+    const expectedOffset = requiredFinality === "official" ? schedule.officialAfterMilliseconds ?? schedule.deliverySlaMilliseconds : schedule.deliverySlaMilliseconds;
+    if (identityDurationMilliseconds(schedule.deliverySlaDuration) !== expectedOffset) {
+      throw new Error("Reporting deliverySlaDuration does not describe the offset its obligations expect");
+    }
+  }
+  if (schedule.alignment === void 0) {
+    if (schedule.periodTimezone !== void 0) {
+      throw new Error("Reporting periodTimezone requires an explicit schedule alignment");
+    }
+    return;
+  }
+  if (!["utc", "account_timezone", "source_timezone", "billing_cycle"].includes(schedule.alignment)) {
+    throw new Error("Reporting schedule alignment is not a recognized value");
+  }
+  const carriesTimezone = schedule.alignment === "billing_cycle" || schedule.alignment === "source_timezone";
+  if (!carriesTimezone && schedule.periodTimezone !== void 0) {
+    throw new Error(`Reporting ${schedule.alignment} alignment must not declare a period timezone`);
+  }
+  if (carriesTimezone && schedule.periodTimezone !== void 0 && schedule.periodTimezone !== sourceTimezone) {
+    throw new Error("Reporting periodTimezone does not match the configured source timezone");
+  }
+  if (schedule.alignment === "billing_cycle") return;
+  if (schedule.alignment === "account_timezone") {
+    throw new Error("Reporting account_timezone alignment is not schedulable by this ledger");
+  }
+  const anchorMs = instant(schedule.anchor, "schedule.anchor");
+  const originMs = reportingScheduleOriginV1(schedule.alignment, sourceTimezone);
+  const offset = anchorMs - originMs;
+  const phase = (offset % schedule.periodMilliseconds + schedule.periodMilliseconds) % schedule.periodMilliseconds;
+  if (phase !== 0) {
+    throw new Error(
+      `Reporting ${schedule.alignment} anchor is not on a period boundary derived from its protocol origin`
+    );
+  }
+  const now = Date.now();
+  const scanStartMs = Math.max(Math.min(anchorMs, now), now - OFFSET_HORIZON_MILLISECONDS);
+  const scanEndMs = Math.max(anchorMs, now) + OFFSET_HORIZON_MILLISECONDS;
+  if (scanEndMs - scanStartMs > MAX_OFFSET_SCAN_MILLISECONDS) {
+    throw new Error("Reporting configuration anchor is too far from the operational horizon to verify its timezone");
+  }
+  if (reportingUtcOffsetChangesV1(sourceTimezone, scanStartMs, scanEndMs)) {
+    throw new Error("Reporting source timezone changes its UTC offset; fixed-length periods cannot express its days");
+  }
+}
 function validateConfigurationAgainstOffering(configuration, offering) {
   assertSupportedReportingAuthoritativeParty(configuration);
   positiveInteger(configuration.schedule.periodMilliseconds, "periodMilliseconds");
@@ -912,6 +998,11 @@ function validateConfigurationAgainstOffering(configuration, offering) {
   for (const offset of configuration.schedule.restatementMilliseconds ?? []) {
     nonnegativeInteger(offset, "restatementMilliseconds");
   }
+  assertScheduleIdentityMatchesBoundaries(
+    configuration.schedule,
+    configuration.sourceTimezone,
+    configuration.requiredFinality
+  );
   const anchor = instant(configuration.schedule.anchor, "schedule.anchor");
   if (configuration.supersededAt && instant(configuration.supersededAt, "supersededAt") <= anchor) {
     throw new Error("Reporting configuration supersession must follow its schedule anchor");
@@ -955,6 +1046,9 @@ function validateConfigurationAgainstOffering(configuration, offering) {
     throw new Error("Authoritative source offerings require official ledger finality");
   }
   if (configuration.feedPurpose === "billing") {
+    if (configuration.requiredFinality !== "official") {
+      throw new Error("Billing reporting requires official ledger finality");
+    }
     if (!configuration.canonicalization || !/^[A-Za-z0-9_.:-]{1,128}$/.test(configuration.canonicalization.id) || !/^https:\/\//.test(configuration.canonicalization.uri) || !/^[a-f0-9]{64}$/i.test(configuration.canonicalization.sha256) || !configuration.canonicalization.primaryKeys.length) {
       throw new Error("Billing reporting requires a pinned canonicalization contract");
     }
@@ -1042,5 +1136,6 @@ function isLeaseLost(value) {
 export {
   UnsupportedReportingFeatureError,
   assertSupportedReportingAuthoritativeParty,
-  createReportingProducer
+  createReportingProducer,
+  reportingCanonicalAdjustmentSha256V1
 };