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

package/dist/lib/reporting/reconciliation.d.mts

@@ -1,4 +1,5 @@
-import type { GetReportingStatusRequest, GetReportingStatusResponse, ReportingCanonicalContentDigest, ReportingControlTotal, ReportingMaterialization, ReportingObligation, ReportingReceipt, ReportingRevision, SyncReportingReceiptsRequest, SyncReportingReceiptsResponse } from '../types/tools.generated.mjs';
+import type { GetReportingStatusRequest, GetReportingStatusResponse, ReportingCanonicalContentDigest, ReportingControlTotal, ReportingMaterialization, ReportingObligation, ReportingReceipt, ReportingConsumerStatus, ReportingRevision, SyncReportingReceiptsRequest, SyncReportingReceiptsResponse } from '../types/tools.generated.mjs';
+import { type ReportingMismatchCodeV1 } from './content-mismatch.mjs';
 import { type ReportingCredentialProvider, type ReportingManifestInspectorOptions, type ReportingResourceReader } from './inspection.mjs';
 type ManagedReportingObligation = ReportingObligation & {
     scope_resolved_at?: string;
@@ -43,6 +44,63 @@ export interface ReportingReconciliationClient {
     syncReportingReceipts(params: SyncReportingReceiptsRequest, options?: {
         signal?: AbortSignal;
     }): Promise<SyncReportingReceiptsResponse>;
+    /**
+     * rc.3 consumer-status loop. Optional so existing adopters keep working:
+     * when it is absent the reconciler still *plans* every status and reports it
+     * on the result, it just cannot post. Supply it only against a seller that
+     * advertises `consumer_status_task`.
+     */
+    syncReportingStatus?(params: {
+        account?: GetReportingStatusRequest['account'];
+        idempotency_key: string;
+        statuses: Array<Record<string, unknown>>;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        status?: string;
+        results?: unknown[];
+    }>;
+    /**
+     * Exact-revision read, the only way a buyer can *earn* a `received`
+     * statement.
+     *
+     * `observed_revision_content_sha256` is defined as the binding digest
+     * "independently recomputed from the exact consumed Core revision binding".
+     * Copying the seller's own `revision_content_sha256` out of the ledger would
+     * hand that digest back unverified and turn buyer-attributed arrival evidence
+     * into an echo. So the reconciler pages `reporting_rows` for the exact
+     * revision, concatenates them in cursor order, and recomputes
+     * SHA-256(JCS({reporting_revision_id,row_count,control_totals,reporting_rows}))
+     * itself.
+     *
+     * Optional: without it the reconciler still plans `received` and
+     * `content_mismatch`, but marks them `suppressed: 'consumption_unavailable'`
+     * and posts neither. Attesting consumption we did not perform is the one
+     * outcome worse than staying silent.
+     */
+    getMediaBuyDelivery?(params: {
+        account?: GetReportingStatusRequest['account'];
+        reporting_revision_id: string;
+        pagination?: {
+            cursor?: string;
+        };
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        status?: string;
+        reporting_revision_binding?: {
+            reporting_revision_id?: string;
+            row_count?: number;
+            control_totals?: ReportingControlTotal[];
+            content_sha256?: string;
+        };
+        reporting_rows?: unknown[];
+        pagination?: {
+            has_more?: boolean;
+            cursor?: string;
+            total_count?: number;
+        };
+    }>;
 }
 export interface ReportingLedger {
     ledgerSnapshotId: string;
@@ -53,11 +111,33 @@ export interface ReportingLedger {
     revisions: ManagedReportingRevision[];
     materializations: ReportingMaterialization[];
     receipts: ReportingReceipt[];
+    /**
+     * The authenticated caller's own append-only status history for this scope.
+     * Sellers disclose no other consumer's statements, so this is the only way to
+     * see the current leaf's *content* — which is what tells the buyer whether it
+     * has anything new to say.
+     */
+    consumerStatuses?: ReportingConsumerStatus[];
 }
 export interface ReportingLedgerLimits {
+    /** Cursor pages per read. Bounds the ledger walk and each revision row read. */
     maxPages?: number;
+    /** Ledger records (obligations + revisions + adjustments) in one snapshot. */
     maxRecords?: number;
+    /**
+     * Wall-clock budget, applied per read: the ledger walk, each receipt write,
+     * each posting batch, the summary read — and, shared across all of them, the
+     * consumer-status consumption pass.
+     */
     maxLoadMs?: number;
+    /**
+     * Rows accumulated from one exact-revision read. Separate from `maxRecords`,
+     * which bounds *ledger* records: a caller who capped a small ledger at a few
+     * hundred records should not thereby cap every revision read at the same
+     * number. Defaults to 100,000, and exceeding it suppresses the statement
+     * rather than accusing the seller.
+     */
+    maxRevisionRows?: number;
 }
 interface ExpectedReportingPeriodBase {
     deliveryConfigId: string;
@@ -79,6 +159,65 @@ interface ExpectedReportingPeriodBase {
     schemaSha256: string;
     schemaDialect: 'https://json-schema.org/draft/2020-12/schema';
     schemaRefPolicy: 'local_fragment_only';
+    /**
+     * `metrics[].name` from the pinned report definition. Supplying it enables
+     * the `metric_missing` arm of `content_mismatch`; omitting it means the buyer
+     * never claims a promised metric is absent, which is the safe default.
+     */
+    committedMetrics?: readonly string[];
+    /**
+     * Units the pinned report definition fixed, keyed by metric/control-total
+     * name. Enables the `currency_mismatch` arm. Omit to skip that check.
+     */
+    metricUnits?: Readonly<Record<string, string>>;
+    /**
+     * The seller's advertised `automated_recovery_window_seconds`, as the buyer
+     * recorded it when accepting the configuration generation.
+     *
+     * It lives on `reporting-delivery-capabilities.json`, **not** on the
+     * obligation, so the ledger cannot supply it — the buyer has to carry its own
+     * copy. Without it the SDK cannot compute the rc.3 posting deadline, so it
+     * marks nothing overdue and posts nothing automatically: silence is a counted
+     * unknown, whereas posting on a guessed clock would churn the status chain.
+     */
+    automatedRecoveryWindowSeconds?: number;
+    /**
+     * The accepted configuration generation's `schedule.delivery_sla`, in
+     * seconds, as the buyer recorded it.
+     *
+     * `expected_at` is "the resolved period end plus this duration". The seller
+     * publishes `expected_at` on an obligation — but `obligation_missing` exists
+     * precisely because there is no obligation, so for that statement the buyer
+     * must derive it. Without this pin the SDK cannot prove a missing period is
+     * yet owed, so it marks nothing overdue and posts nothing: `expected_period`
+     * makes `obligation_missing` valid only at or after `expected_at`, and a
+     * statement dated from the period end is rejected outright by a conformant
+     * seller.
+     */
+    deliverySlaSeconds?: number;
+    /**
+     * Offset used instead of `deliverySlaSeconds` when `requiredFinality` is
+     * `official`, if the seller advertises one.
+     *
+     * `reporting-schedule.json` defines only `delivery_sla`, but this repo's own
+     * seller ingest anchors `expected_at` for official-finality generations on a
+     * separate `officialAfterMilliseconds` and rejects a missing-status statement
+     * dated before it. Without a matching pin a buyer on an official generation
+     * posts at `period.end + delivery_sla`, is refused, and — because that
+     * statement takes no clock input — rebuilds the identical body and is refused
+     * again on every run. Leave it unset when the seller does not advertise one.
+     */
+    officialAfterSeconds?: number;
+    /**
+     * `period.source_timezone` for the accepted generation.
+     *
+     * Preferred over the obligation's echo. The value is part of the
+     * consumer-status chain's logical key, so a seller that varies its echo would
+     * otherwise make the buyer append a fresh statement on every reconcile; the
+     * buyer pinned this when it accepted the generation, and the seller's copy is
+     * an echo of that.
+     */
+    periodSourceTimezone?: string;
     /** Consumer-pinned finality rule, required whenever an official revision is accepted. */
     officialFinality?: {
         policyId: string;
@@ -127,6 +266,42 @@ export interface ReportingCheckpointStore {
     get(key: ReportingCheckpointKey): Promise<ReportingCheckpoint | undefined>;
     put(key: ReportingCheckpointKey, checkpoint: ReportingCheckpoint): Promise<void>;
 }
+/** One consumer-status supersession chain: the logical key the spec defines. */
+export interface ReportingPendingConsumerStatusKey {
+    accountId: string;
+    deliveryConfigId: string;
+    deliveryConfigVersion: number;
+    reportDefinitionId: string;
+    periodStart: string;
+    periodEnd: string;
+}
+export interface ReportingPendingConsumerStatus {
+    /** The exact wire statement, replayed verbatim until the seller confirms it. */
+    statement: Record<string, unknown>;
+    /** Fingerprint of the claim it makes; a changed claim discards it. */
+    claimFingerprint: string;
+}
+/**
+ * Durable memory of a statement that has been built but not yet confirmed.
+ *
+ * `status_as_of` for `received` and `unreadable` is *when this consumer
+ * consumed the revision* — buyer-attributed arrival evidence that the spec
+ * explicitly refuses to let a seller substitute publication time for. That
+ * makes it irreducibly stateful: a stateless reconciler cannot reproduce it,
+ * so after a lost response it would build a different statement for the same
+ * claim.
+ *
+ * Wire this store and the reconciler replays the original statement
+ * byte-for-byte until the seller confirms it, which is the "exact retry" the
+ * spec's `immutability` and `idempotency_key` rules are written around. Leave
+ * it out and a re-plan is a new, valid statement instead: the chain still ends
+ * with exactly one, it just is not literally the same one.
+ */
+export interface ReportingPendingConsumerStatusStore {
+    get(key: ReportingPendingConsumerStatusKey): Promise<ReportingPendingConsumerStatus | undefined>;
+    put(key: ReportingPendingConsumerStatusKey, pending: ReportingPendingConsumerStatus): Promise<void>;
+    clear(key: ReportingPendingConsumerStatusKey): Promise<void>;
+}
 export interface ReportingInspectionContext {
     obligation: ManagedReportingObligation;
     revision: ManagedReportingRevision;
@@ -141,12 +316,173 @@ export interface ObligationReconciliation {
     reportingMaterializationId?: string;
     reasons: string[];
 }
+/**
+ * One consumer status the buyer owes for an expected period, with the deadline
+ * that makes it owed.
+ *
+ * rc.3 moves the buyer's duty off "before you close the scope" and onto a
+ * clock: a current status is owed by `expected_at` plus the seller's advertised
+ * `automated_recovery_window_seconds`. A buyer still retrying at that point
+ * posts `revision_missing` or `unreadable` and supersedes it later rather than
+ * staying silent, because silence is what the seller counts in
+ * `obligation_counts.consumer_status_pending`.
+ */
+export interface ReportingConsumerStatusPlanV1 {
+    deliveryConfigId: string;
+    deliveryConfigVersion: number;
+    reportDefinitionId: string;
+    period: {
+        start: string;
+        end: string;
+        source_timezone: string;
+    };
+    reportingObligationId?: string;
+    reportingRevisionId?: string;
+    observedRevisionContentSha256?: string;
+    /**
+     * The caller's current unsuperseded leaf, when the seller published one. A
+     * new statement must name it; omitting it on a chain that already has a leaf
+     * fails atomically rather than forking.
+     */
+    supersedesReportingStatusId?: string;
+    consumerStatus: 'received' | 'obligation_missing' | 'revision_missing' | 'unreadable' | 'content_mismatch';
+    mismatchCode?: ReportingMismatchCodeV1;
+    failureCode?: 'access_denied' | 'resource_not_found' | 'integrity_mismatch' | 'reader_incompatible' | 'transport_failed';
+    /** `expected_at` + `automated_recovery_window_seconds`, when both are known. */
+    deadline?: string;
+    /** True once the deadline has passed — the status is owed now, not at scope close. */
+    overdue: boolean;
+    /**
+     * When the consumer established this status.
+     *
+     * `undefined` while `requiresConsumption` is still true: a `received`
+     * statement is dated from when the revision became consumable *to this
+     * consumer*, which is not knowable until the buyer has actually read it.
+     */
+    statusAsOf?: string;
+    /**
+     * Earliest instant this statement may legally carry: the later of the
+     * instant it became true and the superseded leaf's own `status_as_of`, since
+     * `time` forbids a chain from moving backwards.
+     */
+    statusAsOfFloor: string;
+    /**
+     * True until the buyer has consumed the named revision and recomputed its
+     * binding digest. `received` and `content_mismatch` both require that
+     * recomputation, so neither may be posted while this is set.
+     */
+    requiresConsumption?: boolean;
+    /**
+     * Why this status was planned but not posted.
+     *
+     * - `unchanged` — the caller's current leaf already says exactly this. Posting
+     *   it again would supersede a statement with its own duplicate, forever;
+     *   `retention_and_limits` calls that pathological churn.
+     * - `leaf_undisclosed` — the seller named a current leaf it did not return, so
+     *   the buyer cannot tell whether it has anything new to say and declines to
+     *   guess.
+     * - `consumption_unavailable` — no exact-revision reader is wired, so the
+     *   buyer cannot honestly attest consumption.
+     * - `posting_unavailable` — no `syncReportingStatus` is wired, so there is
+     *   nothing to append to. Without this the plan reads as live, due and
+     *   unsuppressed while silently going nowhere.
+     * - `period_identity_unknown` — the seller supplied a `period.source_timezone`
+     *   that is not a recognized IANA zone. That value is part of the chain's
+     *   logical key, so substituting one produces a statement the seller refuses
+     *   on every run; `iana_timezone` forbids the substitution by name.
+     * - `local_budget_exhausted` — the buyer's own read budget ran out before it
+     *   could consume the revision. Self-inflicted, so it is silence rather than
+     *   an `unreadable` claim against a seller that did nothing wrong.
+     * - `deadline_unknown` — no posting deadline could be derived, so this period
+     *   will never post. Two causes, both named in `reason`: a pin the buyer has
+     *   to supply is missing, or the seller's own `obligation.expected_at` is
+     *   unreadable and its `schedule.delivery_sla` did not resolve one either.
+     *   Without this value a permanent misconfiguration renders exactly like a
+     *   period that is simply not due yet.
+     * - `chain_indeterminate` — the seller's revision chain forked, or the buyer
+     *   could not walk it. That is the buyer failing to read, not the seller
+     *   failing to publish, and `revision_missing` would blame the wrong party.
+     */
+    suppressed?: 'unchanged' | 'leaf_undisclosed' | 'consumption_unavailable' | 'local_budget_exhausted' | 'deadline_unknown' | 'chain_indeterminate' | 'posting_unavailable' | 'period_identity_unknown';
+    /**
+     * Set when the seller's own `expected_at` is later than the buyer's pinned
+     * expectation by more than its recovery window.
+     *
+     * The statement is still not posted — `expected_period` makes the seller's
+     * instant authoritative, and a locally derived one would be refused. But
+     * without this the period sits at `overdue: false` with `suppressed` unset,
+     * indistinguishable from one that is simply not due yet, which is a silent
+     * kill switch for the whole loop. **Alert on it.**
+     */
+    deadlineBeyondPin?: {
+        declared: string;
+        pinned: string;
+    };
+    /** Why this status, in adopter-readable terms. Never a measurement claim. */
+    reason: string;
+}
+/**
+ * A seller-reported issue the buyer may need to put in front of a human,
+ * carried with the escalation destination so an SDK user can page someone
+ * without re-reading the capability document.
+ */
+export interface ReportingEscalationV1 {
+    reportingObligationId: string;
+    issueId: string;
+    code: string;
+    severity: string;
+    responsibleParty: string;
+    recommendedAction: string;
+    /** Fixed at first emission; age the issue from this, not from the read. */
+    openedAt?: string;
+    issueState?: string;
+    /** Inert correlation text. Never dereference or resolve it. */
+    externalRef?: string;
+    reportingStatusId?: string;
+    /**
+     * Seller's advertised human escalation path. Display metadata only: agents
+     * MUST NOT fetch the URL, send protocol traffic to it, or treat either value
+     * as a credential.
+     */
+    operationsContact?: {
+        url?: string;
+        email?: string;
+    };
+    /** True when `recommended_action` is in the `contact_*` family. */
+    requiresHumanContact: boolean;
+}
 export interface ReportingReconciliationResult {
     definitive: boolean;
     ledger: ReportingLedger;
     obligations: ObligationReconciliation[];
     missingExpectedPeriods: ExpectedReportingPeriod[];
     submittedReceipts: ReportingReceipt[];
+    /** Every status the buyer owes for the reconciled scope, overdue flagged. */
+    consumerStatuses: ReportingConsumerStatusPlanV1[];
+    /** The subset actually posted through `syncReportingStatus` this run. */
+    postedConsumerStatuses: ReportingConsumerStatusPlanV1[];
+    /**
+     * Statuses the seller rejected item-locally, carrying the errors it returned.
+     * `sync_reporting_status` is a partial-success batch, so a rejection is data
+     * the caller has to see — swallowing it leaves a buyer believing it has
+     * discharged a duty it has not.
+     */
+    failedConsumerStatuses: Array<{
+        plan: ReportingConsumerStatusPlanV1;
+        reportingStatusId?: string;
+        errors: unknown[];
+    }>;
+    /**
+     * The seller's own count of obligations past the buyer's posting deadline
+     * with no current status from this caller. Surfaced verbatim; it is a
+     * visibility count over the buyer's silence and never a health input.
+     * `undefined` when the read could not establish it: the client carries no
+     * `syncReportingStatus` (so this seller is not running the loop), the seller
+     * omitted the field, or the summary read failed.
+     */
+    consumerStatusPending?: number;
+    /** Seller-reported issues, with escalation destination attached. */
+    escalations: ReportingEscalationV1[];
     totalsByRevision: Array<{
         reportingRevisionId: string;
         rowCount: number;
@@ -165,6 +501,21 @@ interface ReconcileReportingBaseOptions {
     inspectionRetryBaseDelayMs?: number;
     ledgerLimits?: ReportingLedgerLimits;
     now?: Date;
+    /**
+     * The seller's advertised `operations_contact`, recorded by the buyer from
+     * the capability document. Surfaced on every escalation so an SDK user can
+     * page a human. Inert display metadata — never dereference it.
+     */
+    operationsContact?: {
+        url?: string;
+        email?: string;
+    };
+    /**
+     * Durable memory for statements built but not yet confirmed, so a retry
+     * after a lost response is the same statement rather than a new one. Optional;
+     * see `ReportingPendingConsumerStatusStore` for what changes without it.
+     */
+    pendingConsumerStatusStore?: ReportingPendingConsumerStatusStore;
 }
 type ReportingCheckpointOptions = {
     checkpointStore?: never;
@@ -193,7 +544,16 @@ export declare class ReportingReconciliationError extends Error {
 }
 export declare function isReportingCoverageEvidence(value: unknown): value is ReportingCoverageEvidence;
 export declare function loadReportingLedger(client: ReportingReconciliationClient, request: Omit<GetReportingStatusRequest, 'view' | 'pagination'>, maxSnapshotRestarts?: number, limits?: ReportingLedgerLimits): Promise<ReportingLedger>;
-export declare function evaluateReportingLedger(ledger: ReportingLedger, expectedPeriods: ExpectedReportingPeriod[] | undefined, now?: Date): Omit<ReportingReconciliationResult, 'submittedReceipts'>;
+export declare function evaluateReportingLedger(ledger: ReportingLedger, expectedPeriods: ExpectedReportingPeriod[] | undefined, now?: Date, 
+/**
+ * The seller's advertised `operations_contact`, as the buyer recorded it from
+ * the capability document. It is not carried on any `get_reporting_status`
+ * response, so it cannot be derived here.
+ */
+operationsContact?: {
+    url?: string;
+    email?: string;
+}): Omit<ReportingReconciliationResult, 'submittedReceipts'>;
 export declare function buildReportingReceipt(context: ReportingInspectionContext, observation: ReportingObservation, reportingReceiptId?: string, observedAt?: string): ReportingReceipt;
 export declare function reconcileReporting<TCredential = unknown>(options: ReconcileReportingOptions<TCredential>): Promise<ReportingReconciliationResult>;
 export {};