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

package/dist/lib/protocols/mcp-modern.mjs

@@ -16,6 +16,7 @@ import { is401Error } from "../errors/index.mjs";
 import { withSpan, injectTraceHeaders } from "../observability/tracing.mjs";
 import {
   currentMCPConnectionScopeKey,
+  markMCPConnectionScopeInterrupted,
   isMCPConnectionScopeCacheKeyActive,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending
@@ -255,9 +256,15 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     getCapability: options.signingContext.getCapability,
     adcpVersion: options.signingContext.adcpVersion
   }) : diagnosticFetch;
+  const transportFetch = wrapFetchWithCapture(withPerRequestTraceHeaders(signedFetch));
+  let throttleRetryAfter;
   const transport = new StreamableHTTPClientTransport(new URL(options.agentUrl), {
     requestInit: { headers: splitConnectionHeaders(authHeaders).identity, redirect: "manual" },
-    fetch: wrapFetchWithCapture(withPerRequestTraceHeaders(signedFetch)),
+    fetch: async (input, init) => {
+      const response = await transportFetch(input, init);
+      throttleRetryAfter = response.status === 429 || response.status === 503 ? response.headers.get("retry-after") ?? void 0 : void 0;
+      return response;
+    },
     ...options.authProvider && {
       authProvider: options.authProvider
     }
@@ -300,8 +307,22 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     if (isNegotiationAuthFailure(error) && !skipProbe && presentedStaticCredential(authHeaders, options.authProvider)) {
       return createNegotiatedClient(cacheKey, options, authHeaders, useCachedDiscovery, true);
     }
-    throw error;
+    throw withRetryAfter(error, throttleRetryAfter);
+  }
+}
+function withRetryAfter(error, retryAfter) {
+  if (retryAfter === void 0 || !error || typeof error !== "object") return error;
+  const status = httpStatusOf(error);
+  if (status !== 429 && status !== 503) return error;
+  try {
+    Object.defineProperty(error, "retryAfter", { value: retryAfter, enumerable: false, configurable: true });
+  } catch {
   }
+  return error;
+}
+function retryAfterOf(error) {
+  const value = error && typeof error === "object" ? error.retryAfter : void 0;
+  return typeof value === "string" ? value : void 0;
 }
 async function getOrCreateModernConnection(cacheKey, options, authHeaders) {
   for (let attempt = 0; ; attempt++) {
@@ -321,12 +342,12 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   const promise = createNegotiatedClient(cacheKey, options, authHeaders).then(async (client) => {
     if ((client.getProtocolEra() === "modern" || options.handleLegacy === true) && generation === connectionGeneration) {
       modernConnections.set(cacheKey, client);
-      registerMCPConnectionScopeCleanup("modern", cacheKey, async () => {
+      registerMCPConnectionScopeCleanup("modern", cacheKey, async (terminateSession) => {
         if (modernConnections.get(cacheKey) !== client) return;
         modernConnections.delete(cacheKey);
         legacyConnectionExpiresAt.delete(cacheKey);
         modernDiscoveries.delete(cacheKey);
-        await closeModernClient(client);
+        await closeModernClient(client, terminateSession);
       });
       if (client.getProtocolEra() === "legacy") {
         legacyConnectionExpiresAt.set(cacheKey, Date.now() + LEGACY_CLASSIFICATION_TTL_MS);
@@ -348,7 +369,10 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   return promise;
 }
 async function retireFailedConnection(cacheKey, client, error) {
-  if (isAbortOrTimeoutError(error)) return;
+  if (isAbortOrTimeoutError(error)) {
+    markMCPConnectionScopeInterrupted();
+    return;
+  }
   if (modernConnections.get(cacheKey) === client) {
     modernConnections.delete(cacheKey);
     legacyConnectionExpiresAt.delete(cacheKey);
@@ -517,6 +541,7 @@ async function probeModernMCPConnection(agentUrl, authToken, customHeaders, opti
     options.allowPrivateIp
   );
   const scoped = shouldReuseMCPConnection(options.fetchFn !== void 0);
+  if (isKnownLegacy(cacheKey)) return { connected: false };
   let client;
   return runWithMCPCallContext(
     callContextFor({ customHeaders, requestTimeoutMs: options.requestTimeoutMs }),
@@ -656,6 +681,7 @@ async function closeModernMCPConnections() {
 export {
   closeModernMCPConnections,
   probeModernMCPConnection,
+  retryAfterOf,
   tryCallModernMCPTool,
   tryListModernMCPTools
 };

package/dist/lib/protocols/mcp-scope.d.mts

@@ -1,6 +1,8 @@
-type ScopeCleanup = () => Promise<void>;
+type ScopeCleanup = (terminateSession: boolean) => Promise<void>;
 /** Cache-key suffix for the current caller-owned MCP workflow. */
 export declare function currentMCPConnectionScopeKey(): string | undefined;
+/** Preserve seller work even when a higher layer handles a request timeout. */
+export declare function markMCPConnectionScopeInterrupted(): void;
 /** Whether an LRU entry belongs to a workflow that has not finished yet. */
 export declare function isMCPConnectionScopeCacheKeyActive(cacheKey: string): boolean;
 /** Register one idempotent cache-entry cleanup with the current workflow. */
@@ -20,6 +22,9 @@ export declare function closeCurrentMCPConnectionScope(): Promise<boolean>;
  * Per-call correlation headers, `AbortSignal`s and timeouts do not choose the
  * session. The scope terminates its sessions once, when `fn` settles; pass
  * `{ isolate: true }` to force a fresh scope even when called from inside one.
+ * Explicit workflows terminate sessions at exit even if an inner call returned
+ * submitted/working; the caller owns that lifetime. Implicit task scopes may
+ * close only their local clients when their final result remains nonterminal.
  *
  * @example
  * ```ts

package/dist/lib/protocols/mcp-scope.d.ts

@@ -1,6 +1,8 @@
-type ScopeCleanup = () => Promise<void>;
+type ScopeCleanup = (terminateSession: boolean) => Promise<void>;
 /** Cache-key suffix for the current caller-owned MCP workflow. */
 export declare function currentMCPConnectionScopeKey(): string | undefined;
+/** Preserve seller work even when a higher layer handles a request timeout. */
+export declare function markMCPConnectionScopeInterrupted(): void;
 /** Whether an LRU entry belongs to a workflow that has not finished yet. */
 export declare function isMCPConnectionScopeCacheKeyActive(cacheKey: string): boolean;
 /** Register one idempotent cache-entry cleanup with the current workflow. */
@@ -20,6 +22,9 @@ export declare function closeCurrentMCPConnectionScope(): Promise<boolean>;
  * Per-call correlation headers, `AbortSignal`s and timeouts do not choose the
  * session. The scope terminates its sessions once, when `fn` settles; pass
  * `{ isolate: true }` to force a fresh scope even when called from inside one.
+ * Explicit workflows terminate sessions at exit even if an inner call returned
+ * submitted/working; the caller owns that lifetime. Implicit task scopes may
+ * close only their local clients when their final result remains nonterminal.
  *
  * @example
  * ```ts

package/dist/lib/protocols/mcp-scope.js

@@ -21,18 +21,24 @@ __export(mcp_scope_exports, {
   closeCurrentMCPConnectionScope: () => closeCurrentMCPConnectionScope,
   currentMCPConnectionScopeKey: () => currentMCPConnectionScopeKey,
   isMCPConnectionScopeCacheKeyActive: () => isMCPConnectionScopeCacheKeyActive,
+  markMCPConnectionScopeInterrupted: () => markMCPConnectionScopeInterrupted,
   registerMCPConnectionScopeCleanup: () => registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending: () => registerMCPConnectionScopePending,
   withMCPConnectionScope: () => withMCPConnectionScope
 });
 module.exports = __toCommonJS(mcp_scope_exports);
 var import_node_async_hooks = require("node:async_hooks");
+var import_abort = require('./abort.js');
 const scopeStorage = new import_node_async_hooks.AsyncLocalStorage();
 const activeScopeKeys = /* @__PURE__ */ new Set();
 let nextScopeId = 0;
 function currentMCPConnectionScopeKey() {
   return scopeStorage.getStore()?.cacheKey;
 }
+function markMCPConnectionScopeInterrupted() {
+  const scope = scopeStorage.getStore();
+  if (scope?.preserveOnInterruption) scope.interrupted = true;
+}
 function isMCPConnectionScopeCacheKeyActive(cacheKey) {
   const marker = cacheKey.lastIndexOf("::scope:");
   return marker >= 0 && activeScopeKeys.has(cacheKey.slice(marker + 2));
@@ -55,17 +61,32 @@ async function closeCurrentMCPConnectionScope() {
   }
   const cleanups = [...scope.cleanups.values()];
   scope.cleanups.clear();
-  await Promise.allSettled(cleanups.map((cleanup) => cleanup()));
+  await Promise.allSettled(
+    cleanups.map((cleanup) => cleanup(!scope.signal?.aborted && !scope.interrupted && !scope.preserveSession))
+  );
   return true;
 }
 async function withMCPConnectionScope(fn, options = {}) {
   if (scopeStorage.getStore() && options.isolate !== true) return fn();
   const id = ++nextScopeId;
-  const scope = { id, cacheKey: `scope:${id}`, pending: /* @__PURE__ */ new Set(), cleanups: /* @__PURE__ */ new Map() };
+  const scope = {
+    id,
+    cacheKey: `scope:${id}`,
+    pending: /* @__PURE__ */ new Set(),
+    cleanups: /* @__PURE__ */ new Map(),
+    signal: options.signal,
+    preserveOnInterruption: options.preserveOnInterruption,
+    preserveSessionOnResult: options.preserveSessionOnResult
+  };
   activeScopeKeys.add(scope.cacheKey);
   return scopeStorage.run(scope, async () => {
     try {
-      return await fn();
+      const result = await fn();
+      scope.preserveSession = scope.preserveSessionOnResult?.(result) === true;
+      return result;
+    } catch (error) {
+      if ((0, import_abort.isAbortOrTimeoutError)(error)) markMCPConnectionScopeInterrupted();
+      throw error;
     } finally {
       try {
         await closeCurrentMCPConnectionScope();
@@ -80,6 +101,7 @@ async function withMCPConnectionScope(fn, options = {}) {
   closeCurrentMCPConnectionScope,
   currentMCPConnectionScopeKey,
   isMCPConnectionScopeCacheKeyActive,
+  markMCPConnectionScopeInterrupted,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending,
   withMCPConnectionScope

package/dist/lib/protocols/mcp-scope.mjs

@@ -4,12 +4,17 @@ import { createRequire as __adcpCreateRequire } from "node:module";
 const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
 const require2 = __adcpCreateRequire(import.meta.url);
 import { AsyncLocalStorage } from "node:async_hooks";
+import { isAbortOrTimeoutError } from "./abort.mjs";
 const scopeStorage = new AsyncLocalStorage();
 const activeScopeKeys = /* @__PURE__ */ new Set();
 let nextScopeId = 0;
 function currentMCPConnectionScopeKey() {
   return scopeStorage.getStore()?.cacheKey;
 }
+function markMCPConnectionScopeInterrupted() {
+  const scope = scopeStorage.getStore();
+  if (scope?.preserveOnInterruption) scope.interrupted = true;
+}
 function isMCPConnectionScopeCacheKeyActive(cacheKey) {
   const marker = cacheKey.lastIndexOf("::scope:");
   return marker >= 0 && activeScopeKeys.has(cacheKey.slice(marker + 2));
@@ -32,17 +37,32 @@ async function closeCurrentMCPConnectionScope() {
   }
   const cleanups = [...scope.cleanups.values()];
   scope.cleanups.clear();
-  await Promise.allSettled(cleanups.map((cleanup) => cleanup()));
+  await Promise.allSettled(
+    cleanups.map((cleanup) => cleanup(!scope.signal?.aborted && !scope.interrupted && !scope.preserveSession))
+  );
   return true;
 }
 async function withMCPConnectionScope(fn, options = {}) {
   if (scopeStorage.getStore() && options.isolate !== true) return fn();
   const id = ++nextScopeId;
-  const scope = { id, cacheKey: `scope:${id}`, pending: /* @__PURE__ */ new Set(), cleanups: /* @__PURE__ */ new Map() };
+  const scope = {
+    id,
+    cacheKey: `scope:${id}`,
+    pending: /* @__PURE__ */ new Set(),
+    cleanups: /* @__PURE__ */ new Map(),
+    signal: options.signal,
+    preserveOnInterruption: options.preserveOnInterruption,
+    preserveSessionOnResult: options.preserveSessionOnResult
+  };
   activeScopeKeys.add(scope.cacheKey);
   return scopeStorage.run(scope, async () => {
     try {
-      return await fn();
+      const result = await fn();
+      scope.preserveSession = scope.preserveSessionOnResult?.(result) === true;
+      return result;
+    } catch (error) {
+      if (isAbortOrTimeoutError(error)) markMCPConnectionScopeInterrupted();
+      throw error;
     } finally {
       try {
         await closeCurrentMCPConnectionScope();
@@ -56,6 +76,7 @@ export {
   closeCurrentMCPConnectionScope,
   currentMCPConnectionScopeKey,
   isMCPConnectionScopeCacheKeyActive,
+  markMCPConnectionScopeInterrupted,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending,
   withMCPConnectionScope

package/dist/lib/protocols/mcp.js

@@ -207,10 +207,10 @@ async function getOrCreateConnection(cacheKey, baseUrl, authHeaders, debugLogs,
         throw new Error(`MCP ${label} completed after connection teardown`);
       }
       connectionCache.set(cacheKey, client);
-      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("legacy", cacheKey, async () => {
+      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("legacy", cacheKey, async (terminateSession) => {
         if (connectionCache.get(cacheKey) !== client) return;
         connectionCache.delete(cacheKey);
-        await closeMCPClient(client);
+        await closeMCPClient(client, terminateSession);
       });
       evictLeastRecentlyUsed();
       return client;
@@ -280,10 +280,10 @@ async function getOrCreateOAuthConnection(cacheKey, options) {
         throw new Error("OAuth MCP connection completed after connection teardown");
       }
       oauthConnectionCache.set(cacheKey, client);
-      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("oauth", cacheKey, async () => {
+      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("oauth", cacheKey, async (terminateSession) => {
         if (oauthConnectionCache.get(cacheKey) !== client) return;
         oauthConnectionCache.delete(cacheKey);
-        await closeMCPClient(client);
+        await closeMCPClient(client, terminateSession);
       });
       evictLeastRecentlyUsedOAuth();
       return client;
@@ -337,7 +337,10 @@ async function withCachedOAuthConnectionImpl(options, label, fn) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error
     });
-    if ((0, import_abort.isAbortOrTimeoutError)(error)) throw error;
+    if ((0, import_abort.isAbortOrTimeoutError)(error)) {
+      (0, import_mcp_scope.markMCPConnectionScopeInterrupted)();
+      throw error;
+    }
     if ((0, import_errors.is401Error)(error)) {
       options.debugLogs.push({
         type: "warning",
@@ -405,7 +408,10 @@ async function withCachedConnectionImpl(agentUrl, authToken, authHeaders, debugL
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error
     });
-    if ((0, import_abort.isAbortOrTimeoutError)(error)) throw error;
+    if ((0, import_abort.isAbortOrTimeoutError)(error)) {
+      (0, import_mcp_scope.markMCPConnectionScopeInterrupted)();
+      throw error;
+    }
     if ((0, import_errors.is401Error)(error)) {
       debugLogs.push({
         type: "warning",

package/dist/lib/protocols/mcp.mjs

@@ -35,6 +35,7 @@ import {
 import { closeModernMCPConnections, tryCallModernMCPTool } from "./mcp-modern.mjs";
 import {
   currentMCPConnectionScopeKey,
+  markMCPConnectionScopeInterrupted,
   isMCPConnectionScopeCacheKeyActive,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending
@@ -208,10 +209,10 @@ async function getOrCreateConnection(cacheKey, baseUrl, authHeaders, debugLogs,
         throw new Error(`MCP ${label} completed after connection teardown`);
       }
       connectionCache.set(cacheKey, client);
-      registerMCPConnectionScopeCleanup("legacy", cacheKey, async () => {
+      registerMCPConnectionScopeCleanup("legacy", cacheKey, async (terminateSession) => {
         if (connectionCache.get(cacheKey) !== client) return;
         connectionCache.delete(cacheKey);
-        await closeMCPClient(client);
+        await closeMCPClient(client, terminateSession);
       });
       evictLeastRecentlyUsed();
       return client;
@@ -281,10 +282,10 @@ async function getOrCreateOAuthConnection(cacheKey, options) {
         throw new Error("OAuth MCP connection completed after connection teardown");
       }
       oauthConnectionCache.set(cacheKey, client);
-      registerMCPConnectionScopeCleanup("oauth", cacheKey, async () => {
+      registerMCPConnectionScopeCleanup("oauth", cacheKey, async (terminateSession) => {
         if (oauthConnectionCache.get(cacheKey) !== client) return;
         oauthConnectionCache.delete(cacheKey);
-        await closeMCPClient(client);
+        await closeMCPClient(client, terminateSession);
       });
       evictLeastRecentlyUsedOAuth();
       return client;
@@ -338,7 +339,10 @@ async function withCachedOAuthConnectionImpl(options, label, fn) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error
     });
-    if (isAbortOrTimeoutError(error)) throw error;
+    if (isAbortOrTimeoutError(error)) {
+      markMCPConnectionScopeInterrupted();
+      throw error;
+    }
     if (is401Error(error)) {
       options.debugLogs.push({
         type: "warning",
@@ -406,7 +410,10 @@ async function withCachedConnectionImpl(agentUrl, authToken, authHeaders, debugL
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error
     });
-    if (isAbortOrTimeoutError(error)) throw error;
+    if (isAbortOrTimeoutError(error)) {
+      markMCPConnectionScopeInterrupted();
+      throw error;
+    }
     if (is401Error(error)) {
       debugLogs.push({
         type: "warning",

package/dist/lib/reporting/inspection.js

@@ -502,6 +502,7 @@ function compileRowSchema(schema, maxCompileMs, deadline) {
   assertInspectionDeadline(deadline);
   const startedAt = Date.now();
   const ajv = new Ajv2020({
+    inlineRefs: false,
     strictSchema: true,
     strictTypes: false,
     allErrors: true,

package/dist/lib/reporting/inspection.mjs

@@ -472,6 +472,7 @@ function compileRowSchema(schema, maxCompileMs, deadline) {
   assertInspectionDeadline(deadline);
   const startedAt = Date.now();
   const ajv = new Ajv2020({
+    inlineRefs: false,
     strictSchema: true,
     strictTypes: false,
     allErrors: true,

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

@@ -19,3 +19,8 @@ export declare function evaluateReportingLedgerCoverageV1(query: ReportingLedger
     complete: boolean;
     retainedFrom: string;
 };
+/**
+ * Store-side guard, evaluated under the same account lock as generation writes.
+ * @experimental Storage-facing building block; see docs/guides/REPORTING-STABILITY.md.
+ */
+export declare function assertReportingLedgerHistoryDoesNotOverlap(configuration: ReportingLedgerConfigurationV1, configurations: readonly ReportingLedgerConfigurationV1[]): void;

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

@@ -19,3 +19,8 @@ export declare function evaluateReportingLedgerCoverageV1(query: ReportingLedger
     complete: boolean;
     retainedFrom: string;
 };
+/**
+ * Store-side guard, evaluated under the same account lock as generation writes.
+ * @experimental Storage-facing building block; see docs/guides/REPORTING-STABILITY.md.
+ */
+export declare function assertReportingLedgerHistoryDoesNotOverlap(configuration: ReportingLedgerConfigurationV1, configurations: readonly ReportingLedgerConfigurationV1[]): void;

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

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var coverage_exports = {};
 __export(coverage_exports, {
+  assertReportingLedgerHistoryDoesNotOverlap: () => assertReportingLedgerHistoryDoesNotOverlap,
   evaluateReportingLedgerCoverageV1: () => evaluateReportingLedgerCoverageV1,
   matchingReportingLedgerConfigurations: () => matchingReportingLedgerConfigurations,
   relevantReportingLedgerConfigurations: () => relevantReportingLedgerConfigurations,
@@ -56,7 +57,7 @@ function relevantReportingLedgerConfigurations(configurations, periodStart, peri
   const start = Date.parse(periodStart);
   const end = Date.parse(periodEnd);
   return configurations.filter((configuration) => {
-    const installed = Date.parse(configuration.installedAt);
+    const installed = Date.parse(configuration.historyStart ?? configuration.installedAt);
     const successor = reportingLedgerSuccessor(configuration, configurations);
     const superseded = Math.min(
       successor ? Date.parse(successor.installedAt) : Number.POSITIVE_INFINITY,
@@ -83,7 +84,7 @@ function evaluateReportingLedgerCoverageV1(query, configurations, obligations, l
   let complete = true;
   let retainedFrom;
   for (const configuration of configurations.filter((value) => reportingLedgerConfigurationMatchesScope(query, value))) {
-    const installedAt = Date.parse(configuration.installedAt);
+    const installedAt = Date.parse(configuration.historyStart ?? configuration.installedAt);
     const successor = reportingLedgerSuccessor(configuration, configurations);
     const ownershipEnd = Math.min(
       successor ? Date.parse(successor.installedAt) : Number.POSITIVE_INFINITY,
@@ -108,7 +109,7 @@ function evaluateReportingLedgerCoverageV1(query, configurations, obligations, l
       }
       continue;
     }
-    const firstOwned = Math.max(0, schedule.ceil(installedAt));
+    const firstOwned = configuration.historyStartOrdinal ?? Math.max(0, schedule.ceil(installedAt));
     const ownershipLast = Number.isFinite(ownershipEnd) ? schedule.ceil(ownershipEnd) - 1 : Number.POSITIVE_INFINITY;
     if (ownershipLast < firstOwned) continue;
     const end = Number.isFinite(ownershipLast) ? schedule.boundary(ownershipLast + 1) : Number.POSITIVE_INFINITY;
@@ -135,8 +136,41 @@ function evaluateReportingLedgerCoverageV1(query, configurations, obligations, l
   }
   return { complete, retainedFrom: retainedFrom ?? period.start };
 }
+function assertReportingLedgerHistoryDoesNotOverlap(configuration, configurations) {
+  if (configuration.historyStart === void 0) return;
+  const all = [
+    ...configurations.filter((value) => value.configurationId !== configuration.configurationId),
+    configuration
+  ];
+  const range = (value) => {
+    const schedule2 = (0, import_schedule.reportingPeriodSchedule)(value);
+    const first = value.historyStartOrdinal ?? Math.max(0, schedule2.ceil(Date.parse(value.installedAt)));
+    const successor = reportingLedgerSuccessor(value, all);
+    const end2 = Math.min(
+      successor ? Date.parse(successor.installedAt) : Infinity,
+      value.supersededAt ? Date.parse(value.supersededAt) : Infinity
+    );
+    return [schedule2.boundary(first), Number.isFinite(end2) ? schedule2.boundary(schedule2.ceil(end2)) : Infinity];
+  };
+  const [start, ownershipEnd] = range(configuration);
+  const previous = configurations.find((value) => value.configurationId === configuration.configurationId);
+  const schedule = (0, import_schedule.reportingPeriodSchedule)(configuration);
+  const previousStart = previous?.historyStart !== void 0 ? Date.parse(previous.historyStart) : schedule.boundary(Math.max(0, schedule.ceil(Date.parse(configuration.installedAt))));
+  const end = Math.min(ownershipEnd, previousStart);
+  if (start >= end) return;
+  for (const other of all) {
+    if (other.configurationId === configuration.configurationId || other.account.account_id !== configuration.account.account_id || other.delivery_config_id !== configuration.delivery_config_id)
+      continue;
+    if (Date.parse(other.historyStart ?? other.installedAt) >= end) continue;
+    const [otherStart, otherEnd] = range(other);
+    if (start < end && otherStart < otherEnd && start < otherEnd && otherStart < end) {
+      throw new RangeError("Reporting history overlaps another configuration generation");
+    }
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  assertReportingLedgerHistoryDoesNotOverlap,
   evaluateReportingLedgerCoverageV1,
   matchingReportingLedgerConfigurations,
   relevantReportingLedgerConfigurations,

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

@@ -31,7 +31,7 @@ function relevantReportingLedgerConfigurations(configurations, periodStart, peri
   const start = Date.parse(periodStart);
   const end = Date.parse(periodEnd);
   return configurations.filter((configuration) => {
-    const installed = Date.parse(configuration.installedAt);
+    const installed = Date.parse(configuration.historyStart ?? configuration.installedAt);
     const successor = reportingLedgerSuccessor(configuration, configurations);
     const superseded = Math.min(
       successor ? Date.parse(successor.installedAt) : Number.POSITIVE_INFINITY,
@@ -58,7 +58,7 @@ function evaluateReportingLedgerCoverageV1(query, configurations, obligations, l
   let complete = true;
   let retainedFrom;
   for (const configuration of configurations.filter((value) => reportingLedgerConfigurationMatchesScope(query, value))) {
-    const installedAt = Date.parse(configuration.installedAt);
+    const installedAt = Date.parse(configuration.historyStart ?? configuration.installedAt);
     const successor = reportingLedgerSuccessor(configuration, configurations);
     const ownershipEnd = Math.min(
       successor ? Date.parse(successor.installedAt) : Number.POSITIVE_INFINITY,
@@ -83,7 +83,7 @@ function evaluateReportingLedgerCoverageV1(query, configurations, obligations, l
       }
       continue;
     }
-    const firstOwned = Math.max(0, schedule.ceil(installedAt));
+    const firstOwned = configuration.historyStartOrdinal ?? Math.max(0, schedule.ceil(installedAt));
     const ownershipLast = Number.isFinite(ownershipEnd) ? schedule.ceil(ownershipEnd) - 1 : Number.POSITIVE_INFINITY;
     if (ownershipLast < firstOwned) continue;
     const end = Number.isFinite(ownershipLast) ? schedule.boundary(ownershipLast + 1) : Number.POSITIVE_INFINITY;
@@ -110,7 +110,40 @@ function evaluateReportingLedgerCoverageV1(query, configurations, obligations, l
   }
   return { complete, retainedFrom: retainedFrom ?? period.start };
 }
+function assertReportingLedgerHistoryDoesNotOverlap(configuration, configurations) {
+  if (configuration.historyStart === void 0) return;
+  const all = [
+    ...configurations.filter((value) => value.configurationId !== configuration.configurationId),
+    configuration
+  ];
+  const range = (value) => {
+    const schedule2 = reportingPeriodSchedule(value);
+    const first = value.historyStartOrdinal ?? Math.max(0, schedule2.ceil(Date.parse(value.installedAt)));
+    const successor = reportingLedgerSuccessor(value, all);
+    const end2 = Math.min(
+      successor ? Date.parse(successor.installedAt) : Infinity,
+      value.supersededAt ? Date.parse(value.supersededAt) : Infinity
+    );
+    return [schedule2.boundary(first), Number.isFinite(end2) ? schedule2.boundary(schedule2.ceil(end2)) : Infinity];
+  };
+  const [start, ownershipEnd] = range(configuration);
+  const previous = configurations.find((value) => value.configurationId === configuration.configurationId);
+  const schedule = reportingPeriodSchedule(configuration);
+  const previousStart = previous?.historyStart !== void 0 ? Date.parse(previous.historyStart) : schedule.boundary(Math.max(0, schedule.ceil(Date.parse(configuration.installedAt))));
+  const end = Math.min(ownershipEnd, previousStart);
+  if (start >= end) return;
+  for (const other of all) {
+    if (other.configurationId === configuration.configurationId || other.account.account_id !== configuration.account.account_id || other.delivery_config_id !== configuration.delivery_config_id)
+      continue;
+    if (Date.parse(other.historyStart ?? other.installedAt) >= end) continue;
+    const [otherStart, otherEnd] = range(other);
+    if (start < end && otherStart < otherEnd && start < otherEnd && otherStart < end) {
+      throw new RangeError("Reporting history overlaps another configuration generation");
+    }
+  }
+}
 export {
+  assertReportingLedgerHistoryDoesNotOverlap,
   evaluateReportingLedgerCoverageV1,
   matchingReportingLedgerConfigurations,
   relevantReportingLedgerConfigurations,

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

@@ -922,11 +922,14 @@ function nextExpectedAt(health, selected, query, configurations, ledgerAsOf) {
 }
 function nextActivePeriodStart(configuration, configurations, ledgerAsOf) {
   const asOf = Date.parse(ledgerAsOf);
-  const installed = Date.parse(configuration.installedAt);
+  const installed = Date.parse(configuration.historyStart ?? configuration.installedAt);
   const ownershipEnd = reportingLedgerConfigurationOwnershipEnd(configuration, configurations);
   if (installed > asOf || ownershipEnd <= asOf) return [];
   const schedule = (0, import_schedule.reportingPeriodSchedule)(configuration);
-  const ordinal = Math.max(0, schedule.ceil(installed), schedule.floor(asOf) + 1);
+  const ordinal = Math.max(
+    configuration.historyStartOrdinal ?? Math.max(0, schedule.ceil(installed)),
+    schedule.floor(asOf) + 1
+  );
   const start = schedule.boundary(ordinal);
   if (start >= ownershipEnd) return [];
   schedule.period(ordinal);
@@ -934,13 +937,13 @@ function nextActivePeriodStart(configuration, configurations, ledgerAsOf) {
 }
 function nextObligationDue(configuration, configurations, query, ledgerAsOf) {
   const schedule = (0, import_schedule.reportingPeriodSchedule)(configuration);
-  const installed = Date.parse(configuration.installedAt);
+  const installed = Date.parse(configuration.historyStart ?? configuration.installedAt);
   const ownershipEnd = reportingLedgerConfigurationOwnershipEnd(configuration, configurations);
   const period = (0, import_coverage.reportingLedgerEffectivePeriod)(query, ledgerAsOf);
   const periodStart = Date.parse(period.start);
   const periodEnd = Date.parse(period.end);
   const expectedOffset = configuration.schedule.deliverySlaMilliseconds;
-  const firstOwned = Math.max(0, schedule.ceil(installed));
+  const firstOwned = configuration.historyStartOrdinal ?? Math.max(0, schedule.ceil(installed));
   const lastOwned = schedule.ceil(ownershipEnd) - 1;
   if (lastOwned < firstOwned) return [];
   const end = Number.isFinite(lastOwned) ? schedule.boundary(lastOwned + 1) : Number.POSITIVE_INFINITY;

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

@@ -906,11 +906,14 @@ function nextExpectedAt(health, selected, query, configurations, ledgerAsOf) {
 }
 function nextActivePeriodStart(configuration, configurations, ledgerAsOf) {
   const asOf = Date.parse(ledgerAsOf);
-  const installed = Date.parse(configuration.installedAt);
+  const installed = Date.parse(configuration.historyStart ?? configuration.installedAt);
   const ownershipEnd = reportingLedgerConfigurationOwnershipEnd(configuration, configurations);
   if (installed > asOf || ownershipEnd <= asOf) return [];
   const schedule = reportingPeriodSchedule(configuration);
-  const ordinal = Math.max(0, schedule.ceil(installed), schedule.floor(asOf) + 1);
+  const ordinal = Math.max(
+    configuration.historyStartOrdinal ?? Math.max(0, schedule.ceil(installed)),
+    schedule.floor(asOf) + 1
+  );
   const start = schedule.boundary(ordinal);
   if (start >= ownershipEnd) return [];
   schedule.period(ordinal);
@@ -918,13 +921,13 @@ function nextActivePeriodStart(configuration, configurations, ledgerAsOf) {
 }
 function nextObligationDue(configuration, configurations, query, ledgerAsOf) {
   const schedule = reportingPeriodSchedule(configuration);
-  const installed = Date.parse(configuration.installedAt);
+  const installed = Date.parse(configuration.historyStart ?? configuration.installedAt);
   const ownershipEnd = reportingLedgerConfigurationOwnershipEnd(configuration, configurations);
   const period = reportingLedgerEffectivePeriod(query, ledgerAsOf);
   const periodStart = Date.parse(period.start);
   const periodEnd = Date.parse(period.end);
   const expectedOffset = configuration.schedule.deliverySlaMilliseconds;
-  const firstOwned = Math.max(0, schedule.ceil(installed));
+  const firstOwned = configuration.historyStartOrdinal ?? Math.max(0, schedule.ceil(installed));
   const lastOwned = schedule.ceil(ownershipEnd) - 1;
   if (lastOwned < firstOwned) return [];
   const end = Number.isFinite(lastOwned) ? schedule.boundary(lastOwned + 1) : Number.POSITIVE_INFINITY;