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

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

@@ -2,12 +2,29 @@ import type { ReportingLedgerStatusTransitionV1, ReportingLedgerStore, Reporting
 export declare function reconcileReportingStatusLifecycleV1(input: {
     store: ReportingLedgerStore;
     reporting_obligation_id: string;
-    ledgerAsOf: string;
+    /**
+     * Cutoff to reconcile at. Omit it — and prefer omitting it outside a
+     * deadline sweep — to let the store supply an authoritative instant at
+     * full precision instead of a millisecond-truncated host `Date`.
+     */
+    ledgerAsOf?: string;
+    /** Fallback clock for a store that cannot supply its own instant. */
+    now?: () => Date;
     subscribers?: readonly ReportingLedgerSubscriberV1[];
-}): Promise<ReportingLedgerStatusTransitionV1 | null>;
+}, attempt?: number): Promise<ReportingLedgerStatusTransitionV1 | null>;
 export declare function retryReportingStatusNotificationsV1(input: {
     store: ReportingLedgerStore;
-    ledgerAsOf: string;
+    /** Omit to let the store supply an authoritative instant. */
+    ledgerAsOf?: string;
+    /**
+     * Clock to use only when the store cannot supply its own instant.
+     *
+     * A store backed by a database is authoritative and this is ignored. An
+     * in-memory or simulated-time store has no clock of its own, so a driver
+     * that advances time must still be able to say what "now" means without
+     * pinning a cutoff that would be written into the watermark verbatim.
+     */
+    fallbackLedgerAsOf?: string;
     account_id?: string;
     subscribers?: readonly ReportingLedgerSubscriberV1[];
     limit?: number;
@@ -15,7 +32,17 @@ export declare function retryReportingStatusNotificationsV1(input: {
 /** Reconcile bounded clock-driven waiting→delayed→action_required transitions. */
 export declare function reconcileReportingStatusDeadlinesV1(input: {
     store: ReportingLedgerStore;
-    ledgerAsOf: string;
+    /** Omit to let the store supply an authoritative instant. */
+    ledgerAsOf?: string;
+    /**
+     * Clock to use only when the store cannot supply its own instant.
+     *
+     * A store backed by a database is authoritative and this is ignored. An
+     * in-memory or simulated-time store has no clock of its own, so a driver
+     * that advances time must still be able to say what "now" means without
+     * pinning a cutoff that would be written into the watermark verbatim.
+     */
+    fallbackLedgerAsOf?: string;
     account_id?: string;
     subscribers?: readonly ReportingLedgerSubscriberV1[];
     limit?: number;

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

@@ -25,96 +25,303 @@ __export(lifecycle_exports, {
 module.exports = __toCommonJS(lifecycle_exports);
 var import_node_crypto = require("node:crypto");
 var import_source = require('../source/index.js');
+var import_handler = require('./handler.js');
+var import_instant = require('./instant.js');
 var import_health = require('./health.js');
-async function reconcileReportingStatusLifecycleV1(input) {
+async function resolveLedgerAsOf(input, attempt) {
+  const resolved = await input.store.readLedgerInstant?.() ?? (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+  if (input.ledgerAsOf === void 0) return resolved;
+  if (input.store.readLedgerInstant) {
+    return attempt === 0 && (0, import_instant.compareReportingInstants)(input.ledgerAsOf, resolved) <= 0 ? input.ledgerAsOf : resolved;
+  }
+  if (attempt === 0) return input.ledgerAsOf;
+  return (0, import_instant.compareReportingInstants)(resolved, input.ledgerAsOf) > 0 ? resolved : input.ledgerAsOf;
+}
+async function reconcileEachIsolated(input, obligationIds) {
+  assertNotificationModesCompatible(input.store, input.subscribers);
+  for (const reporting_obligation_id of obligationIds) {
+    try {
+      await reconcileReportingStatusLifecycleV1({
+        store: input.store,
+        reporting_obligation_id,
+        // Selection needs one instant; each reconcile resolves its own so the
+        // watermark it writes is the cutoff it actually read at. The sweep's
+        // instant is handed down only as a fallback clock, for a store that
+        // has none of its own — pinning it would put the sweep's cutoff into
+        // every watermark, which is the skew problem over again.
+        ...input.pinnedLedgerAsOf !== void 0 ? { ledgerAsOf: input.pinnedLedgerAsOf } : {},
+        now: () => new Date(input.ledgerAsOf),
+        subscribers: input.subscribers
+      });
+    } catch {
+      await input.store.recordLifecycleFailure?.({ reporting_obligation_id }).catch(() => void 0);
+    }
+  }
+  return obligationIds.length;
+}
+const MAX_LIFECYCLE_CAS_ATTEMPTS = 3;
+function assertNotificationModesCompatible(store, subscribers) {
+  if (store.transactionalNotificationActivity === true && (subscribers?.length ?? 0) > 0) {
+    throw new Error("Transactional reporting notification activity and legacy subscribers are mutually exclusive");
+  }
+}
+async function retryLifecycle(input, attempt) {
+  if (attempt + 1 >= MAX_LIFECYCLE_CAS_ATTEMPTS) {
+    await input.store.recordLifecycleFailure?.({ reporting_obligation_id: input.reporting_obligation_id }).catch(() => void 0);
+    return null;
+  }
+  return reconcileReportingStatusLifecycleV1(input, attempt + 1);
+}
+async function reconcileReportingStatusLifecycleV1(input, attempt = 0) {
   const obligation = await input.store.getObligation(input.reporting_obligation_id);
   if (!obligation) throw new Error("Reporting obligation is unavailable");
+  const transactionalNotifications = input.store.transactionalNotificationActivity === true;
+  assertNotificationModesCompatible(input.store, input.subscribers);
+  let ledgerAsOf = await resolveLedgerAsOf(input, attempt);
   const revisions = await input.store.listRevisions(obligation.reporting_obligation_id);
-  const projection = (0, import_health.projectReportingObligationHealthV1)(
+  let projected = revisions;
+  const projectCore = (at) => (0, import_health.projectReportingObligationHealthV1)(
+    obligation,
+    projected,
+    at,
+    (0, import_instant.compareReportingInstants)(obligation.period.end, at) <= 0
+  );
+  let coreProjection = projectCore(ledgerAsOf);
+  let composed = await composeManagedLifecycleProjection(
+    { store: input.store, ledgerAsOf },
     obligation,
-    revisions,
-    input.ledgerAsOf,
-    Date.parse(obligation.period.end) <= Date.parse(input.ledgerAsOf)
+    projected,
+    coreProjection
   );
+  const visibleRevisionIds = composed.visibleRevisionIds;
+  const scoped = visibleRevisionIds ? revisions.filter((value) => visibleRevisionIds.includes(value.reporting_revision_id)) : revisions;
+  if (composed.resolvedLedgerAsOf !== void 0 && (0, import_instant.compareReportingInstants)(composed.resolvedLedgerAsOf, ledgerAsOf) !== 0 || scoped.length !== projected.length) {
+    ledgerAsOf = composed.resolvedLedgerAsOf ?? ledgerAsOf;
+    projected = scoped;
+    coreProjection = projectCore(ledgerAsOf);
+    composed = await composeManagedLifecycleProjection(
+      { store: input.store, ledgerAsOf },
+      obligation,
+      projected,
+      coreProjection
+    );
+  }
+  const projection = composed.projection;
   const transitions = await input.store.listTransitions(obligation.reporting_obligation_id);
-  for (const pending of transitions.filter((value) => !value.notifiedAt)) {
+  const pendingTransitions = transitions.filter((value) => !value.notifiedAt);
+  if (transactionalNotifications && pendingTransitions.length > 0) {
+    throw new Error(
+      "Drain or explicitly resolve legacy pending reporting transitions before enabling transactional notification activity"
+    );
+  }
+  for (const pending of pendingTransitions) {
+    if (pending.previousHealth === pending.health) {
+      await input.store.markTransitionNotified(pending.transitionId, ledgerAsOf);
+      continue;
+    }
     if (await notifyTransition(pending, obligation.account.account_id, input.subscribers)) {
-      await input.store.markTransitionNotified(pending.transitionId, input.ledgerAsOf);
+      await input.store.markTransitionNotified(pending.transitionId, ledgerAsOf);
     }
   }
   const latest = transitions.at(-1);
-  if (latest && Date.parse(input.ledgerAsOf) < Date.parse(latest.occurredAt)) return null;
+  if (latest && (0, import_instant.compareReportingInstants)(ledgerAsOf, latest.occurredAt) < 0) return null;
   const previousHealth = latest?.health ?? "waiting";
+  const finality = observedFinality(projected);
+  const previousFinality = await resolveFinalityBaseline(
+    input.store,
+    obligation.reporting_obligation_id,
+    latest,
+    finality
+  );
   const nextIssueIds = new Set(projection.issues.map((issue) => issue.issueId));
-  const transition = previousHealth === projection.health ? void 0 : {
+  const transition = previousHealth === projection.health && previousFinality === finality ? void 0 : {
     transitionId: `rst_${(0, import_node_crypto.createHash)("sha256").update(
       (0, import_source.canonicalJsonV1)([
         obligation.reporting_obligation_id,
         previousHealth,
         projection.health,
+        previousFinality,
+        finality,
         [...nextIssueIds].sort(),
-        input.ledgerAsOf
+        ledgerAsOf
       ])
     ).digest("base64url").slice(0, 32)}`,
     reporting_obligation_id: obligation.reporting_obligation_id,
     previousHealth,
     health: projection.health,
+    previousFinality,
+    finality,
     issueIds: [...nextIssueIds].sort(),
-    occurredAt: input.ledgerAsOf
+    occurredAt: ledgerAsOf
   };
+  if (composed.obligatedConsumerRosterVersion !== void 0 && input.store.readObligatedConsumerRosterVersion) {
+    const current = await input.store.readObligatedConsumerRosterVersion({
+      reporting_obligation_id: obligation.reporting_obligation_id
+    });
+    if (current !== composed.obligatedConsumerRosterVersion) {
+      return retryLifecycle(input, attempt);
+    }
+  }
   const applied = await input.store.applyLifecycleProjection({
     reporting_obligation_id: obligation.reporting_obligation_id,
     expectedRevisionIds: revisions.map((value) => value.reporting_revision_id),
     expectedPreviousHealth: previousHealth,
+    expectedPreviousFinality: previousFinality,
     expectedObligationState: obligation.state,
     expectedAttemptCount: obligation.attemptCount,
     projectedIssues: projection.issues,
-    ledgerAsOf: input.ledgerAsOf,
-    ...transition ? { transition } : {}
+    ledgerAsOf,
+    ...transition ? { transition } : {},
+    ...composed.managedStateVersion !== void 0 ? {
+      expectedManagedStateVersion: composed.managedStateVersion,
+      processedManagedStateVersion: composed.managedStateVersion
+    } : {},
+    ...composed.obligatedConsumerRosterVersion !== void 0 ? {
+      processedObligatedConsumerRosterVersion: composed.obligatedConsumerRosterVersion,
+      // The re-check above is outside any transaction, so it leaves a
+      // window the store closes by fencing on the same value.
+      expectedObligatedConsumerRosterVersion: composed.obligatedConsumerRosterVersion
+    } : {}
   });
-  if (!applied.applied || !transition || !applied.transitionInserted) return null;
+  if (!applied.applied) return retryLifecycle(input, attempt);
+  if (!transition || !applied.transitionInserted) return null;
+  if (transactionalNotifications) return { ...transition, notifiedAt: ledgerAsOf };
+  if (transition.previousHealth === transition.health) {
+    await input.store.markTransitionNotified(transition.transitionId, ledgerAsOf);
+    return { ...transition, notifiedAt: ledgerAsOf };
+  }
   const notified = await notifyTransition(transition, obligation.account.account_id, input.subscribers);
-  if (notified) await input.store.markTransitionNotified(transition.transitionId, input.ledgerAsOf);
-  return notified ? { ...transition, notifiedAt: input.ledgerAsOf } : transition;
+  if (notified) await input.store.markTransitionNotified(transition.transitionId, ledgerAsOf);
+  return notified ? { ...transition, notifiedAt: ledgerAsOf } : transition;
+}
+const CONSUMER_SCOPED_RECEIPT_ISSUE_CODES = /* @__PURE__ */ new Set([
+  "RECEIPT_REQUIRED",
+  "RECEIPT_REJECTED",
+  "ADJUSTMENT_RECEIPT_REQUIRED",
+  "ADJUSTMENT_RECEIPT_REJECTED"
+]);
+async function composeManagedLifecycleProjection(input, obligation, revisions, coreProjection) {
+  if (!input.store.getManagedLifecycleProjection) return { projection: coreProjection };
+  const managed = await input.store.getManagedLifecycleProjection({
+    reporting_obligation_id: obligation.reporting_obligation_id,
+    ledgerAsOf: input.ledgerAsOf
+  });
+  if (!managed) return { projection: coreProjection };
+  const stored = await input.store.listAdjustments(obligation.reporting_obligation_id);
+  const visibleAdjustmentIds = managed.visibleAdjustmentIds;
+  const adjustments = visibleAdjustmentIds ? stored.filter((value) => visibleAdjustmentIds.includes(value.reporting_adjustment_id)) : stored.filter((value) => (0, import_instant.compareReportingInstants)(value.createdAt, input.ledgerAsOf) <= 0);
+  const rosterAuthoritative = managed.obligatedConsumerRosterComplete === true && managed.receiptEvidenceComplete !== false;
+  const observed = rosterAuthoritative ? [] : managed.consumers;
+  const byConsumer = new Map(observed.map((value) => [value.consumer_id, value]));
+  for (const consumerId of managed.obligatedConsumerIds ?? []) {
+    if (!byConsumer.has(consumerId)) {
+      const submitted = managed.consumers.find((value) => value.consumer_id === consumerId);
+      byConsumer.set(consumerId, submitted ?? { consumer_id: consumerId, receipts: [], adjustmentReceipts: [] });
+    }
+  }
+  const consumers = [...byConsumer.values()];
+  if (!consumers.length || managed.binding.reconciliation_mode === "consumer_receipt" && !rosterAuthoritative) {
+    consumers.push({ receipts: [], adjustmentReceipts: [] });
+  }
+  let health = coreProjection.health;
+  let satisfied = coreProjection.satisfied;
+  let suppressedReceiptIssue = false;
+  const issues = new Map(coreProjection.issues.map((value) => [value.issueId, value]));
+  for (const consumer of consumers) {
+    const projected = (0, import_handler.projectManagedDelivery)({
+      obligation,
+      binding: managed.binding,
+      revisions,
+      adjustments,
+      materializations: managed.materializations,
+      materializationHistory: managed.materializationHistory,
+      receipts: consumer.receipts,
+      adjustmentReceipts: consumer.adjustmentReceipts,
+      base: coreProjection,
+      ledgerAsOf: input.ledgerAsOf,
+      // Scoped to the consumer being projected. An acceptance A left behind
+      // must never settle the obligation for B, which would let a webhook go
+      // complete while B's own read still says action_required.
+      // The anonymous fail-safe consumer owns no acceptances. Matching every
+      // tombstone to it let one consumer's pruned acceptance satisfy the
+      // stand-in for "someone unknown may still owe a receipt", flipping an
+      // incomplete-roster obligation to complete while real consumers were
+      // still pending.
+      tombstonedAcceptedSubjects: consumer.consumer_id === void 0 ? [] : (managed.tombstonedAcceptedSubjects ?? []).filter((value) => value.consumerId === consumer.consumer_id),
+      tombstonedDeliveredRevisionIds: managed.tombstonedDeliveredRevisionIds
+    });
+    if (!projected) continue;
+    health = (0, import_handler.moreSevereReportingHealthV1)(health, projected.projection.health);
+    satisfied = satisfied && projected.projection.satisfied;
+    for (const issue of projected.projection.issues) {
+      if (CONSUMER_SCOPED_RECEIPT_ISSUE_CODES.has(issue.code)) {
+        suppressedReceiptIssue = true;
+        continue;
+      }
+      issues.set(issue.issueId, issue);
+    }
+  }
+  if (suppressedReceiptIssue) {
+    const issueId = `reporting-issue.reconciliation-outstanding.${obligation.reporting_obligation_id}`;
+    issues.set(issueId, {
+      issueId,
+      reporting_obligation_id: obligation.reporting_obligation_id,
+      code: "RECEIPT_REQUIRED",
+      severity: "action_required",
+      responsibleParty: "buyer",
+      recommendedAction: "contact_buyer",
+      openedAt: obligation.expectedAt,
+      observedAt: input.ledgerAsOf
+    });
+  }
+  return {
+    projection: { ...coreProjection, health, satisfied, issues: [...issues.values()] },
+    ...managed.managedStateVersion !== void 0 ? { managedStateVersion: managed.managedStateVersion } : {},
+    ...managed.obligatedConsumerRosterVersion !== void 0 ? { obligatedConsumerRosterVersion: managed.obligatedConsumerRosterVersion } : {},
+    ...managed.resolvedLedgerAsOf !== void 0 ? { resolvedLedgerAsOf: managed.resolvedLedgerAsOf } : {},
+    ...managed.visibleRevisionIds !== void 0 ? { visibleRevisionIds: managed.visibleRevisionIds } : {}
+  };
+}
+async function resolveFinalityBaseline(store, reporting_obligation_id, latest, observed) {
+  if (!latest) return "none";
+  if (latest.finality) return latest.finality;
+  if (store.resolveTransitionFinalityBaseline) {
+    return store.resolveTransitionFinalityBaseline(reporting_obligation_id);
+  }
+  return observed;
+}
+function observedFinality(revisions) {
+  if (revisions.some((value) => value.finality === "official")) return "official";
+  return revisions.length > 0 ? "snapshot" : "none";
 }
 async function retryReportingStatusNotificationsV1(input) {
   const pending = await input.store.listPendingTransitions({
     ...input.account_id ? { account_id: input.account_id } : {},
     limit: input.limit ?? 100
   });
+  const ledgerAsOf = input.ledgerAsOf ?? await input.store.readLedgerInstant?.() ?? input.fallbackLedgerAsOf ?? (/* @__PURE__ */ new Date()).toISOString();
   const obligationIds = [...new Set(pending.map((value) => value.reporting_obligation_id))];
-  for (const reporting_obligation_id of obligationIds) {
-    await reconcileReportingStatusLifecycleV1({
-      store: input.store,
-      reporting_obligation_id,
-      ledgerAsOf: input.ledgerAsOf,
-      subscribers: input.subscribers
-    });
-  }
-  return obligationIds.length;
+  return reconcileEachIsolated({ ...input, ledgerAsOf, pinnedLedgerAsOf: input.ledgerAsOf }, obligationIds);
 }
 async function reconcileReportingStatusDeadlinesV1(input) {
   const limit = input.limit ?? 1e3;
   if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1e3) throw new RangeError("limit must be 1..1000");
-  const asOf = Date.parse(input.ledgerAsOf);
-  if (!Number.isFinite(asOf)) throw new TypeError("ledgerAsOf must be an RFC 3339 instant");
+  const ledgerAsOf = input.ledgerAsOf ?? await input.store.readLedgerInstant?.() ?? input.fallbackLedgerAsOf ?? (/* @__PURE__ */ new Date()).toISOString();
+  if (!Number.isFinite(Date.parse(ledgerAsOf))) throw new TypeError("ledgerAsOf must be an RFC 3339 instant");
+  await input.store.refreshObligatedConsumerRosterVersions?.({
+    ...input.account_id ? { account_id: input.account_id } : {},
+    limit
+  });
   const due = (await input.store.listLifecycleDueObligations({
-    ledgerAsOf: input.ledgerAsOf,
+    ledgerAsOf,
     ...input.account_id ? { account_id: input.account_id } : {},
     limit
   })).map((value) => value.reporting_obligation_id);
-  for (const reporting_obligation_id of due) {
-    await reconcileReportingStatusLifecycleV1({
-      store: input.store,
-      reporting_obligation_id,
-      ledgerAsOf: input.ledgerAsOf,
-      subscribers: input.subscribers
-    });
-  }
-  return due.length;
+  return reconcileEachIsolated({ ...input, ledgerAsOf, pinnedLedgerAsOf: input.ledgerAsOf }, due);
 }
 async function notifyTransition(transition, accountId, configured) {
   const subscribers = (configured ?? []).filter((value) => value.account_id === accountId);
+  if (subscribers.length === 0) return true;
   if (subscribers.length > 64) throw new Error("Reporting status subscriber fanout exceeds 64");
   const results = await Promise.allSettled(
     subscribers.map(