@adcp/sdk 17.0.0-beta.1 → 17.0.0-beta.2

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

@@ -10,9 +10,10 @@ import {
   reportingScheduleOriginV1,
   reportingUtcOffsetChangesV1,
   REPORTING_SOURCE_CONTRACT_VERSION_V1,
+  ReportingInstantV1Schema,
   validateReportingSourceExecutionV1
 } from "../source/index.mjs";
-import { reportingLedgerSuccessor } from "./coverage.mjs";
+import { assertReportingLedgerHistoryDoesNotOverlap, reportingLedgerSuccessor } from "./coverage.mjs";
 import {
   assertReportingCalendarDayPeriod,
   assertReportingCalendarDaySource,
@@ -50,7 +51,10 @@ function createReportingProducer(options) {
     subscribersByAccount.set(subscriber.account_id, count);
   }
   return {
-    async installConfiguration(input) {
+    async installConfiguration(input, installOptions = {}) {
+      if (Object.hasOwn(input, "historyStart") || Object.hasOwn(input, "historyStartOrdinal")) {
+        throw new TypeError("Reporting history must be supplied through trusted install options");
+      }
       const normalizedInput = {
         ...structuredClone(input),
         schedule: {
@@ -77,6 +81,19 @@ function createReportingProducer(options) {
         if (!replayFingerprints.includes(replay.semanticFingerprint)) {
           throw new Error("Reporting configuration generation is immutable");
         }
+        if (installOptions.historyStart !== void 0) {
+          const requested = historyInstant(installOptions.historyStart);
+          const ownedStart = replay.historyStart !== void 0 ? Date.parse(replay.historyStart) : void 0;
+          if (ownedStart !== void 0 && requested === ownedStart) return replay;
+          if (requested > Date.now()) throw new RangeError("Reporting historyStart must not be in the future");
+          if (ownedStart !== void 0 && requested >= ownedStart) return replay;
+          const schedule = reportingPeriodSchedule(replay);
+          const start = schedule.boundary(schedule.ceil(requested));
+          const previous = ownedStart ?? schedule.boundary(Math.max(0, schedule.ceil(Date.parse(replay.installedAt))));
+          if (start < previous) {
+            throw new Error("Use extendConfigurationHistory to change an installed history boundary");
+          }
+        }
         return replay;
       }
       validateConfigurationAgainstOffering(normalizedInput, requiredOffering(offeringById, normalizedInput.offeringId));
@@ -109,12 +126,59 @@ function createReportingProducer(options) {
         installedAt,
         semanticFingerprint: calendarRules ? reportingCalendarDayFingerprint(normalizedInput, calendarRules) : semanticFingerprint
       };
-      return (await options.store.putConfiguration(configuration)).value;
+      if (installOptions.historyStart !== void 0) {
+        Object.assign(
+          configuration,
+          normalizeConfigurationHistory(
+            configuration,
+            installOptions.historyStart,
+            requiredOffering(offeringById, configuration.offeringId),
+            Date.parse(installedAt)
+          )
+        );
+      }
+      assertReportingLedgerHistoryDoesNotOverlap(configuration, existing);
+      const stored = (await options.store.putConfiguration(configuration)).value;
+      if (configuration.historyStart !== void 0) {
+        const storedSchedule = stored.historyStart === void 0 ? reportingPeriodSchedule(stored) : void 0;
+        const storedStart = stored.historyStart !== void 0 ? Date.parse(stored.historyStart) : storedSchedule.boundary(Math.max(0, storedSchedule.ceil(Date.parse(stored.installedAt))));
+        if (storedStart > Date.parse(configuration.historyStart)) {
+          throw new Error("Use extendConfigurationHistory to change an installed history boundary");
+        }
+      }
+      return stored;
+    },
+    async extendConfigurationHistory(input) {
+      if (!options.store.extendConfigurationHistory) {
+        throw new TypeError("Reporting ledger store does not support history extension");
+      }
+      const configuration = (await options.store.listConfigurations()).find(
+        (value) => value.configurationId === input.configurationId
+      );
+      if (!configuration) throw new Error("Unknown reporting configuration");
+      if (configuration.historyStart !== void 0) {
+        const requested = historyInstant(input.historyStart);
+        if (requested === Date.parse(configuration.historyStart)) return configuration;
+        const schedule = reportingPeriodSchedule(configuration);
+        if (schedule.boundary(schedule.ceil(requested)) === Date.parse(configuration.historyStart)) {
+          return configuration;
+        }
+      }
+      const history = normalizeConfigurationHistory(
+        configuration,
+        input.historyStart,
+        requiredOffering(offeringById, configuration.offeringId),
+        Date.now()
+      );
+      return options.store.extendConfigurationHistory({ configurationId: input.configurationId, ...history });
     },
     async planObligations(now = (/* @__PURE__ */ new Date()).toISOString(), planOptions = {}) {
       const nowMs = instant(now, "now");
       const maxObligations = planOptions.maxObligations ?? 1e3;
       positiveInteger(maxObligations, "maxObligations");
+      const maxHistory = planOptions.maxHistoryObligationsPerSource ?? maxObligations;
+      nonnegativeInteger(maxHistory, "maxHistoryObligationsPerSource");
+      const historyBySource = /* @__PURE__ */ new Map();
       const created = [];
       let attempted = 0;
       const configurations = (await options.store.listConfigurations(planOptions.account_id)).sort(
@@ -122,74 +186,86 @@ function createReportingProducer(options) {
       );
       const obligationsByAccount = /* @__PURE__ */ new Map();
       const retiredByAccount = /* @__PURE__ */ new Map();
-      for (const configuration of configurations) {
-        const successor = reportingLedgerSuccessor(configuration, configurations);
-        const anchor = instant(configuration.schedule.anchor, "schedule.anchor");
-        const effectiveFrom = Math.max(anchor, instant(configuration.installedAt, "installedAt"));
-        let schedule;
-        try {
-          schedule = reportingPeriodSchedule(configuration);
-        } catch (error) {
-          const predecessor = configurations.find(
-            (candidate) => reportingLedgerSuccessor(candidate, configurations)?.configurationId === configuration.configurationId
-          );
-          if (isFrozenCalendarRulesMismatch(error) && !successor && predecessor && runtimeCanResolveCalendarGeneration(predecessor)) {
+      for (const historyPass of [false, true]) {
+        for (const configuration of configurations) {
+          const successor = reportingLedgerSuccessor(configuration, configurations);
+          const anchor = instant(configuration.schedule.anchor, "schedule.anchor");
+          const effectiveFrom = configuration.historyStart ? instant(configuration.historyStart, "historyStart") : Math.max(anchor, instant(configuration.installedAt, "installedAt"));
+          let schedule;
+          try {
+            schedule = reportingPeriodSchedule(configuration);
+          } catch (error) {
+            const predecessor = configurations.find(
+              (candidate) => reportingLedgerSuccessor(candidate, configurations)?.configurationId === configuration.configurationId
+            );
+            if (isFrozenCalendarRulesMismatch(error) && !successor && predecessor && runtimeCanResolveCalendarGeneration(predecessor)) {
+              continue;
+            }
+            if (!isFrozenCalendarRulesMismatch(error) || !await supersededCalendarGenerationIsDurablyCovered(options.store, configuration, successor)) {
+              throw error;
+            }
             continue;
           }
-          if (!isFrozenCalendarRulesMismatch(error) || !await supersededCalendarGenerationIsDurablyCovered(options.store, configuration, successor)) {
-            throw error;
+          const generationEndValue = Math.min(
+            successor ? instant(successor.installedAt, "successor.installedAt") : Number.POSITIVE_INFINITY,
+            configuration.supersededAt ? instant(configuration.supersededAt, "supersededAt") : Number.POSITIVE_INFINITY
+          );
+          const generationEnd = Number.isFinite(generationEndValue) ? generationEndValue : void 0;
+          const effectiveUntil = Math.min(nowMs, generationEnd ?? nowMs);
+          const ownedFirst = configuration.historyStartOrdinal ?? Math.max(0, schedule.ceil(effectiveFrom));
+          const liveFirst = Math.max(0, schedule.ceil(instant(configuration.installedAt, "installedAt")));
+          const first = historyPass ? ownedFirst : Math.max(ownedFirst, liveFirst);
+          const ownershipLast = generationEnd ? schedule.ceil(effectiveUntil) - 1 : Number.POSITIVE_INFINITY;
+          if (ownershipLast < first) continue;
+          const latestClosed = schedule.floor(
+            Number.isFinite(ownershipLast) ? Math.min(nowMs, schedule.boundary(ownershipLast + 1)) : nowMs
+          ) - 1;
+          const last = Math.min(ownershipLast, latestClosed, historyPass ? liveFirst - 1 : Number.POSITIVE_INFINITY);
+          let accountObligations = obligationsByAccount.get(configuration.account.account_id);
+          if (!accountObligations) {
+            accountObligations = await options.store.listObligations(configuration.account.account_id);
+            obligationsByAccount.set(configuration.account.account_id, accountObligations);
           }
-          continue;
-        }
-        const generationEndValue = Math.min(
-          successor ? instant(successor.installedAt, "successor.installedAt") : Number.POSITIVE_INFINITY,
-          configuration.supersededAt ? instant(configuration.supersededAt, "supersededAt") : Number.POSITIVE_INFINITY
-        );
-        const generationEnd = Number.isFinite(generationEndValue) ? generationEndValue : void 0;
-        const effectiveUntil = Math.min(nowMs, generationEnd ?? nowMs);
-        const first = Math.max(0, schedule.ceil(effectiveFrom));
-        const ownershipLast = generationEnd ? schedule.ceil(effectiveUntil) - 1 : Number.POSITIVE_INFINITY;
-        if (ownershipLast < first) continue;
-        const latestClosed = schedule.floor(
-          Number.isFinite(ownershipLast) ? Math.min(nowMs, schedule.boundary(ownershipLast + 1)) : nowMs
-        ) - 1;
-        const last = Math.min(ownershipLast, latestClosed);
-        let accountObligations = obligationsByAccount.get(configuration.account.account_id);
-        if (!accountObligations) {
-          accountObligations = await options.store.listObligations(configuration.account.account_id);
-          obligationsByAccount.set(configuration.account.account_id, accountObligations);
-        }
-        let accountRetired = retiredByAccount.get(configuration.account.account_id);
-        if (!accountRetired) {
-          accountRetired = await options.store.listRetiredObligationOrdinals?.(configuration.account.account_id) ?? [];
-          retiredByAccount.set(configuration.account.account_id, accountRetired);
-        }
-        const existingOrdinals = [
-          ...accountObligations.filter((value) => value.configurationId === configuration.configurationId).map((value) => value.periodOrdinal),
-          ...accountRetired.filter((value) => value.configurationId === configuration.configurationId).map((value) => value.periodOrdinal)
-        ];
-        const candidates = missingOrdinals(first, last, existingOrdinals, maxObligations - attempted);
-        for (const ordinal of candidates) {
-          attempted += 1;
-          const obligation = planObligation(configuration, ordinal, now);
-          const written = await options.store.putObligation(obligation);
-          if (written.inserted) {
-            created.push(written.value);
-            await reconcileReportingStatusLifecycleV1({
-              store: options.store,
-              reporting_obligation_id: written.value.reporting_obligation_id,
-              // 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
-            });
+          let accountRetired = retiredByAccount.get(configuration.account.account_id);
+          if (!accountRetired) {
+            accountRetired = await options.store.listRetiredObligationOrdinals?.(configuration.account.account_id) ?? [];
+            retiredByAccount.set(configuration.account.account_id, accountRetired);
+          }
+          const existingOrdinals = [
+            ...accountObligations.filter((value) => value.configurationId === configuration.configurationId).map((value) => value.periodOrdinal),
+            ...accountRetired.filter((value) => value.configurationId === configuration.configurationId).map((value) => value.periodOrdinal)
+          ];
+          const historyRemaining = maxHistory - (historyBySource.get(configuration.offeringId) ?? 0);
+          const candidates = missingOrdinals(
+            first,
+            last,
+            existingOrdinals,
+            Math.min(maxObligations - attempted, historyPass ? historyRemaining : maxObligations)
+          );
+          for (const ordinal of candidates) {
+            attempted += 1;
+            if (historyPass)
+              historyBySource.set(configuration.offeringId, (historyBySource.get(configuration.offeringId) ?? 0) + 1);
+            const obligation = planObligation(configuration, ordinal, now);
+            const written = await options.store.putObligation(obligation);
+            if (written.inserted) {
+              created.push(written.value);
+              await reconcileReportingStatusLifecycleV1({
+                store: options.store,
+                reporting_obligation_id: written.value.reporting_obligation_id,
+                // 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
+              });
+            }
+            if (attempted >= maxObligations) return created;
           }
-          if (attempted >= maxObligations) return created;
         }
       }
       return created;
@@ -197,6 +273,9 @@ function createReportingProducer(options) {
     async runWorker(workerOptions = {}) {
       const now = workerOptions.now ?? (() => /* @__PURE__ */ new Date());
       const maxIterations = workerOptions.maxIterations ?? 25;
+      const maxHistory = workerOptions.maxHistorySlicesPerSource ?? 10;
+      nonnegativeInteger(maxHistory, "maxHistorySlicesPerSource");
+      const historyBySource = /* @__PURE__ */ new Map();
       const retryDelay = workerOptions.retryDelayMilliseconds ?? 3e4;
       const executionDeadline = workerOptions.executionDeadlineMilliseconds ?? EXECUTION_DEADLINE_MS;
       const settlementGrace = workerOptions.settlementGraceMilliseconds ?? DEFAULT_SETTLEMENT_GRACE_MS;
@@ -210,6 +289,10 @@ function createReportingProducer(options) {
       if (settlementGrace > MAX_SETTLEMENT_GRACE_MS) {
         throw new RangeError(`settlementGraceMilliseconds must not exceed ${MAX_SETTLEMENT_GRACE_MS}`);
       }
+      const historyOfferingIds = /* @__PURE__ */ new Set([
+        ...offeringById.keys(),
+        ...(await options.store.listConfigurations(workerOptions.account_id)).map((value) => value.offeringId)
+      ]);
       const owner = `reporting-worker-${randomUUID()}`;
       const counts = { claimed: 0, revisionsCommitted: 0, notReady: 0, failed: 0, reconcilesDeferred: 0 };
       const reconcileQuietly = async (reporting_obligation_id, nowAt) => {
@@ -250,14 +333,35 @@ function createReportingProducer(options) {
           owner,
           now: nowValue.toISOString(),
           leaseMilliseconds: DEFAULT_LEASE_MS,
+          excludeHistoryOfferingIds: [.../* @__PURE__ */ new Set([...historyOfferingIds, ...historyBySource.keys()])].filter(
+            (id) => (historyBySource.get(id) ?? 0) >= maxHistory
+          ),
           ...workerOptions.account_id ? { account_id: workerOptions.account_id } : {}
         });
         if (!lease) break;
+        if (lease.obligation.history && (historyBySource.get(lease.obligation.offeringId) ?? 0) >= maxHistory) {
+          await options.store.releaseObligationLease(lease);
+          throw new TypeError("Reporting ledger store must honor excludeHistoryOfferingIds");
+        }
         counts.claimed += 1;
+        if (lease.obligation.history) {
+          const sourceId = lease.obligation.offeringId;
+          historyBySource.set(sourceId, (historyBySource.get(sourceId) ?? 0) + 1);
+        }
         let executionDeadlineTimer;
-        let activeRecoveryDeadlineAt = lease.obligation.recoveryDeadlineAt;
+        let activeRecoveryDeadlineAt = lease.obligation.historyRecoveryDeadlineAt ?? lease.obligation.recoveryDeadlineAt;
         try {
           const obligation = lease.obligation;
+          if (obligation.history && !obligation.historyRecoveryDeadlineAt) {
+            obligation.historyRecoveryDeadlineAt = new Date(
+              Math.max(
+                Date.parse(obligation.recoveryDeadlineAt),
+                nowValue.getTime() + obligation.schedule.recoveryWindowMilliseconds
+              )
+            ).toISOString();
+            activeRecoveryDeadlineAt = obligation.historyRecoveryDeadlineAt;
+            await options.store.updateObligation(obligation, lease);
+          }
           const offering = requiredOffering(offeringById, obligation.offeringId);
           if (isReportingCalendarDay(obligation.schedule, obligation.period.sourceTimezone)) {
             try {
@@ -283,7 +387,10 @@ function createReportingProducer(options) {
             if (scheduledAt) {
               const recoveryWindow = instant(obligation.recoveryDeadlineAt, "recoveryDeadlineAt") - instant(obligation.expectedAt, "expectedAt");
               activeRecoveryDeadlineAt = new Date(
-                instant(scheduledAt, "nextPublicationAt") + recoveryWindow
+                Math.max(
+                  obligation.history ? Date.parse(activeRecoveryDeadlineAt) : Number.NEGATIVE_INFINITY,
+                  instant(scheduledAt, "nextPublicationAt") + recoveryWindow
+                )
               ).toISOString();
             }
           }
@@ -454,6 +561,42 @@ async function supersededCalendarGenerationIsDurablyCovered(store, configuration
     await store.listObligations(configuration.account.account_id)
   );
 }
+function historyInstant(value) {
+  const parsed = ReportingInstantV1Schema.safeParse(value);
+  if (!parsed.success) {
+    throw new TypeError("historyStart must be a valid RFC 3339 instant with at most millisecond precision");
+  }
+  return instant(parsed.data, "historyStart");
+}
+function normalizeConfigurationHistory(configuration, requested, offering, now) {
+  const requestedMs = historyInstant(requested);
+  if (requestedMs < now - offering.retentionDays * 864e5) {
+    throw new RangeError("Reporting historyStart is outside source retentionDays");
+  }
+  if (requestedMs > now) throw new RangeError("Reporting historyStart must not be in the future");
+  const schedule = reportingPeriodSchedule(configuration);
+  const ordinal = schedule.ceil(requestedMs);
+  const start = schedule.boundary(ordinal);
+  const previousStart = configuration.historyStart ? Date.parse(configuration.historyStart) : schedule.boundary(
+    Math.max(
+      0,
+      schedule.ceil(Math.max(Date.parse(configuration.schedule.anchor), Date.parse(configuration.installedAt)))
+    )
+  );
+  if (requestedMs > previousStart || start > previousStart) {
+    throw new RangeError("Reporting historyStart may only move earlier");
+  }
+  if (isReportingCalendarDay(configuration.schedule, configuration.sourceTimezone)) {
+    assertReportingCalendarDaySource(configuration.schedule, configuration.sourceTimezone, offering, now, start);
+    const previousFirst = configuration.historyStartOrdinal ?? Math.max(0, schedule.ceil(previousStart));
+    for (let selected = ordinal; selected < previousFirst; selected += 1) schedule.period(selected);
+  } else if (configuration.schedule.alignment && configuration.schedule.alignment !== "billing_cycle") {
+    if (reportingUtcOffsetChangesV1(configuration.sourceTimezone, start, Math.max(now, start))) {
+      throw new Error("Reporting history crosses a timezone offset change; install a calendar-day generation");
+    }
+  }
+  return { historyStart: new Date(start).toISOString(), historyStartOrdinal: ordinal };
+}
 function planObligation(configuration, periodOrdinal, createdAt) {
   const schedule = reportingPeriodSchedule(configuration);
   const { start, end } = schedule.period(periodOrdinal);
@@ -482,6 +625,7 @@ function planObligation(configuration, periodOrdinal, createdAt) {
     ...configuration.finalityPolicy ? { finalityPolicy: structuredClone(configuration.finalityPolicy) } : {},
     ...configuration.canonicalization ? { canonicalization: structuredClone(configuration.canonicalization) } : {},
     periodOrdinal,
+    ...configuration.historyStart !== void 0 && periodOrdinal < Math.max(0, schedule.ceil(Date.parse(configuration.installedAt))) ? { history: true } : {},
     period: {
       start: new Date(start).toISOString(),
       end: new Date(end).toISOString(),
@@ -548,7 +692,10 @@ function sourceRequest(obligation, offering, previous, adjustments, now) {
       windowing: structuredClone(offering.windowing)
     },
     finality: revisionKind === "correction" ? { revisionKind, supersedesPublicationId: latest.sourcePublicationId } : { revisionKind },
-    trigger: { kind: obligation.attemptCount ? "retry" : "scheduled_poll", id: `trigger-${obligation.attemptCount}` },
+    trigger: {
+      kind: obligation.attemptCount ? "retry" : obligation.history ? "backfill" : "scheduled_poll",
+      id: `trigger-${obligation.attemptCount}`
+    },
     sourceRequest: { groupIds: [] },
     coverage: {
       expected: "full",

package/dist/lib/reporting/ledger/schedule.d.mts

@@ -1,7 +1,7 @@
 import { type ReportingSourceOfferingV1 } from '../source/index.mjs';
 import type { ReportingCalendarRulesV1, ReportingLedgerConfigurationV1 } from './types.mjs';
 type Schedule = ReportingLedgerConfigurationV1['schedule'];
-type ConfigurationInput = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules'>;
+type ConfigurationInput = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules' | 'historyStart' | 'historyStartOrdinal'>;
 interface PeriodSchedule {
     boundary(ordinal: number): number;
     floor(instant: number): number;
@@ -49,7 +49,7 @@ export declare function reportingCalendarDayNeedsNewIdentity(input: Configuratio
 /** Shared by planning, coverage, projections and consumer status eligibility. */
 export declare function reportingPeriodSchedule(configuration: ReportingLedgerConfigurationV1): PeriodSchedule;
 /** Refuse a day the declared source cannot produce losslessly before accepting it. */
-export declare function assertReportingCalendarDaySource(schedule: Schedule, sourceTimezone: string, source: ReportingSourceOfferingV1, now: number): void;
+export declare function assertReportingCalendarDaySource(schedule: Schedule, sourceTimezone: string, source: ReportingSourceOfferingV1, now: number, historyStart?: number): void;
 /** Recheck the actual period before writing, including periods beyond the install horizon. */
 export declare function assertReportingCalendarDayPeriod(schedule: Schedule, sourceTimezone: string, source: ReportingSourceOfferingV1, start: number, end: number): void;
 export {};

package/dist/lib/reporting/ledger/schedule.d.ts

@@ -1,7 +1,7 @@
 import { type ReportingSourceOfferingV1 } from '../source';
 import type { ReportingCalendarRulesV1, ReportingLedgerConfigurationV1 } from './types';
 type Schedule = ReportingLedgerConfigurationV1['schedule'];
-type ConfigurationInput = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules'>;
+type ConfigurationInput = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules' | 'historyStart' | 'historyStartOrdinal'>;
 interface PeriodSchedule {
     boundary(ordinal: number): number;
     floor(instant: number): number;
@@ -49,7 +49,7 @@ export declare function reportingCalendarDayNeedsNewIdentity(input: Configuratio
 /** Shared by planning, coverage, projections and consumer status eligibility. */
 export declare function reportingPeriodSchedule(configuration: ReportingLedgerConfigurationV1): PeriodSchedule;
 /** Refuse a day the declared source cannot produce losslessly before accepting it. */
-export declare function assertReportingCalendarDaySource(schedule: Schedule, sourceTimezone: string, source: ReportingSourceOfferingV1, now: number): void;
+export declare function assertReportingCalendarDaySource(schedule: Schedule, sourceTimezone: string, source: ReportingSourceOfferingV1, now: number, historyStart?: number): void;
 /** Recheck the actual period before writing, including periods beyond the install horizon. */
 export declare function assertReportingCalendarDayPeriod(schedule: Schedule, sourceTimezone: string, source: ReportingSourceOfferingV1, start: number, end: number): void;
 export {};

package/dist/lib/reporting/ledger/schedule.js

@@ -105,10 +105,10 @@ function isFrozenCalendarRulesMismatch(error) {
   return error instanceof Error && /calendar timezone rules differ from this stored generation/.test(error.message);
 }
 function frozenCalendarObligationsCoverOwnership(configuration, ownershipEnd, obligations) {
-  const first = configuration.calendarRules?.firstOwnedOrdinal;
-  const firstBoundary = configuration.calendarRules?.firstOwnedBoundary;
+  const first = configuration.historyStartOrdinal ?? configuration.calendarRules?.firstOwnedOrdinal;
+  const firstBoundary = configuration.historyStart ?? configuration.calendarRules?.firstOwnedBoundary;
   const firstBoundaryMs = firstBoundary ? Date.parse(firstBoundary) : Number.NaN;
-  if (!Number.isSafeInteger(first) || first < 0 || !Number.isFinite(firstBoundaryMs) || !Number.isFinite(ownershipEnd)) {
+  if (!Number.isSafeInteger(first) || first < 0 && configuration.historyStart === void 0 || !Number.isFinite(firstBoundaryMs) || !Number.isFinite(ownershipEnd)) {
     return false;
   }
   const owned = obligations.filter((value) => value.configurationId === configuration.configurationId).sort((left, right) => left.periodOrdinal - right.periodOrdinal);
@@ -238,6 +238,8 @@ function reportingPeriodSchedule(configuration) {
   const {
     configurationId: _id,
     installedAt: _installedAt,
+    historyStart: _historyStart,
+    historyStartOrdinal: _historyStartOrdinal,
     semanticFingerprint,
     calendarRules,
     ...input
@@ -276,8 +278,9 @@ function reportingPeriodSchedule(configuration) {
     period: (ordinal) => canonicalCalendarPeriod(assertUnchanged(ordinal), assertUnchanged(ordinal + 1))
   };
 }
-function assertReportingCalendarDaySource(schedule, sourceTimezone, source, now) {
-  const { calendar, first, last } = calendarOrdinals(schedule, sourceTimezone, now);
+function assertReportingCalendarDaySource(schedule, sourceTimezone, source, now, historyStart) {
+  const { calendar, first: liveFirst, last } = calendarOrdinals(schedule, sourceTimezone, now);
+  const first = historyStart === void 0 ? liveFirst : Math.min(liveFirst, calendar.ceil(historyStart));
   for (let ordinal = first; ordinal < last; ordinal += 1) {
     assertReportingCalendarDayPeriod(
       schedule,

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

@@ -71,10 +71,10 @@ function isFrozenCalendarRulesMismatch(error) {
   return error instanceof Error && /calendar timezone rules differ from this stored generation/.test(error.message);
 }
 function frozenCalendarObligationsCoverOwnership(configuration, ownershipEnd, obligations) {
-  const first = configuration.calendarRules?.firstOwnedOrdinal;
-  const firstBoundary = configuration.calendarRules?.firstOwnedBoundary;
+  const first = configuration.historyStartOrdinal ?? configuration.calendarRules?.firstOwnedOrdinal;
+  const firstBoundary = configuration.historyStart ?? configuration.calendarRules?.firstOwnedBoundary;
   const firstBoundaryMs = firstBoundary ? Date.parse(firstBoundary) : Number.NaN;
-  if (!Number.isSafeInteger(first) || first < 0 || !Number.isFinite(firstBoundaryMs) || !Number.isFinite(ownershipEnd)) {
+  if (!Number.isSafeInteger(first) || first < 0 && configuration.historyStart === void 0 || !Number.isFinite(firstBoundaryMs) || !Number.isFinite(ownershipEnd)) {
     return false;
   }
   const owned = obligations.filter((value) => value.configurationId === configuration.configurationId).sort((left, right) => left.periodOrdinal - right.periodOrdinal);
@@ -204,6 +204,8 @@ function reportingPeriodSchedule(configuration) {
   const {
     configurationId: _id,
     installedAt: _installedAt,
+    historyStart: _historyStart,
+    historyStartOrdinal: _historyStartOrdinal,
     semanticFingerprint,
     calendarRules,
     ...input
@@ -242,8 +244,9 @@ function reportingPeriodSchedule(configuration) {
     period: (ordinal) => canonicalCalendarPeriod(assertUnchanged(ordinal), assertUnchanged(ordinal + 1))
   };
 }
-function assertReportingCalendarDaySource(schedule, sourceTimezone, source, now) {
-  const { calendar, first, last } = calendarOrdinals(schedule, sourceTimezone, now);
+function assertReportingCalendarDaySource(schedule, sourceTimezone, source, now, historyStart) {
+  const { calendar, first: liveFirst, last } = calendarOrdinals(schedule, sourceTimezone, now);
+  const first = historyStart === void 0 ? liveFirst : Math.min(liveFirst, calendar.ceil(historyStart));
   for (let ordinal = first; ordinal < last; ordinal += 1) {
     assertReportingCalendarDayPeriod(
       schedule,

package/dist/lib/reporting/ledger/status-ingest.d.mts

@@ -195,7 +195,7 @@ export declare const SyncReportingStatusRequestV1Schema: z.ZodObject<{
         brand: z.ZodObject<{
             domain: z.ZodString;
             brand_id: z.ZodOptional<z.ZodString>;
-            countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            countries: z.ZodOptional<import("../../validation/nonempty-array.mjs").NonemptyArraySchema<z.ZodString>>;
         }, z.core.$loose>;
         operator: z.ZodString;
         operator_unit: z.ZodOptional<z.ZodObject<{

package/dist/lib/reporting/ledger/status-ingest.d.ts

@@ -195,7 +195,7 @@ export declare const SyncReportingStatusRequestV1Schema: z.ZodObject<{
         brand: z.ZodObject<{
             domain: z.ZodString;
             brand_id: z.ZodOptional<z.ZodString>;
-            countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            countries: z.ZodOptional<import("../../validation/nonempty-array").NonemptyArraySchema<z.ZodString>>;
         }, z.core.$loose>;
         operator: z.ZodString;
         operator_unit: z.ZodOptional<z.ZodObject<{

package/dist/lib/reporting/ledger/status-ingest.js

@@ -310,7 +310,7 @@ function isExactPeriod(configuration, configurations, period) {
   const scheduleAnchor = new Date(Date.parse(configuration.schedule.anchor)).toISOString();
   let ordinal;
   let firstOwnedOrdinal;
-  const effectiveFrom = (0, import_instant.compareReportingInstants)(scheduleAnchor, configuration.installedAt) >= 0 ? scheduleAnchor : configuration.installedAt;
+  const effectiveFrom = configuration.historyStart ?? ((0, import_instant.compareReportingInstants)(scheduleAnchor, configuration.installedAt) >= 0 ? scheduleAnchor : configuration.installedAt);
   if ((0, import_instant.compareReportingInstants)(period.start, effectiveFrom) < 0) return false;
   if ((0, import_schedule.isReportingCalendarDay)(configuration.schedule, configuration.sourceTimezone)) {
     const schedule = (0, import_schedule.reportingPeriodSchedule)(configuration);
@@ -324,10 +324,11 @@ function isExactPeriod(configuration, configurations, period) {
       first + ((0, import_instant.compareReportingInstants)(effectiveFrom, new Date(schedule.boundary(first)).toISOString()) > 0 ? 1 : 0)
     );
   } else {
-    const selected = (0, import_instant.reportingPeriodOrdinal)(period.start, scheduleAnchor, duration);
+    const eligibilityAnchor = configuration.historyStart ?? scheduleAnchor;
+    const selected = (0, import_instant.reportingPeriodOrdinal)(period.start, eligibilityAnchor, duration);
     if (selected === null || !(0, import_instant.reportingInstantHasDuration)(period.start, period.end, duration)) return false;
     ordinal = selected;
-    firstOwnedOrdinal = (0, import_instant.reportingDurationCeilOrdinal)(scheduleAnchor, effectiveFrom, duration);
+    firstOwnedOrdinal = (0, import_instant.reportingDurationCeilOrdinal)(eligibilityAnchor, effectiveFrom, duration);
   }
   return ordinal >= firstOwnedOrdinal;
 }

package/dist/lib/reporting/ledger/status-ingest.mjs

@@ -300,7 +300,7 @@ function isExactPeriod(configuration, configurations, period) {
   const scheduleAnchor = new Date(Date.parse(configuration.schedule.anchor)).toISOString();
   let ordinal;
   let firstOwnedOrdinal;
-  const effectiveFrom = compareReportingInstants(scheduleAnchor, configuration.installedAt) >= 0 ? scheduleAnchor : configuration.installedAt;
+  const effectiveFrom = configuration.historyStart ?? (compareReportingInstants(scheduleAnchor, configuration.installedAt) >= 0 ? scheduleAnchor : configuration.installedAt);
   if (compareReportingInstants(period.start, effectiveFrom) < 0) return false;
   if (isReportingCalendarDay(configuration.schedule, configuration.sourceTimezone)) {
     const schedule = reportingPeriodSchedule(configuration);
@@ -314,10 +314,11 @@ function isExactPeriod(configuration, configurations, period) {
       first + (compareReportingInstants(effectiveFrom, new Date(schedule.boundary(first)).toISOString()) > 0 ? 1 : 0)
     );
   } else {
-    const selected = reportingPeriodOrdinal(period.start, scheduleAnchor, duration);
+    const eligibilityAnchor = configuration.historyStart ?? scheduleAnchor;
+    const selected = reportingPeriodOrdinal(period.start, eligibilityAnchor, duration);
     if (selected === null || !reportingInstantHasDuration(period.start, period.end, duration)) return false;
     ordinal = selected;
-    firstOwnedOrdinal = reportingDurationCeilOrdinal(scheduleAnchor, effectiveFrom, duration);
+    firstOwnedOrdinal = reportingDurationCeilOrdinal(eligibilityAnchor, effectiveFrom, duration);
   }
   return ordinal >= firstOwnedOrdinal;
 }