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

package/dist/lib/reporting/service/conformance.mjs

@@ -0,0 +1,68 @@
+import {
+  createInlineReportingSourceExecutor,
+  runReportingSourceReplayConformanceV1
+} from "../source/index.mjs";
+async function runReliableReportingServiceConformanceV1(options) {
+  const source = options.adapter.executor ?? createInlineReportingSourceExecutor(options.adapter.fetchSlice, options.adapter.sourceOffering);
+  const manifest = await runReportingSourceReplayConformanceV1({
+    level: "basic",
+    executor: source,
+    objectReader: source,
+    request: structuredClone(options.replayRequest)
+  });
+  const first = await options.service.installConfiguration(options.primary.configuration, options.primary.context);
+  const replay = await options.service.installConfiguration(options.primary.configuration, options.primary.context);
+  const isolated = await options.service.installConfiguration(options.isolated.configuration, options.isolated.context);
+  if (first.configurationId !== replay.configurationId || first.semanticFingerprint !== replay.semanticFingerprint) {
+    throw new Error("Reliable reporting configuration replay was not idempotent");
+  }
+  if (first.account.account_id === isolated.account.account_id || first.configurationId === isolated.configurationId || first.account.account_id !== options.primary.context.account.id || isolated.account.account_id !== options.isolated.context.account.id) {
+    throw new Error("Reliable reporting configuration identity is not account isolated");
+  }
+  if (first.sourceSettings.currency !== options.primary.configuration.expectedCurrency || isolated.sourceSettings.currency !== options.isolated.configuration.expectedCurrency) {
+    throw new Error("Reliable reporting configuration did not freeze trusted currency");
+  }
+  assertTruthfulCoreCapabilities(options.service);
+  options.service.start({ intervalMilliseconds: 6e4, accountIds: [] });
+  if (!options.service.running) throw new Error("Reliable reporting lifecycle did not start");
+  await options.service.stop();
+  if (options.service.running) throw new Error("Reliable reporting lifecycle did not stop");
+  return {
+    checks: [
+      "adapter_replay",
+      "account_isolation",
+      "frozen_currency",
+      "lifecycle_start_stop",
+      "capability_truthfulness"
+    ],
+    manifest
+  };
+}
+function assertTruthfulCoreCapabilities(service) {
+  const capabilities = service.capabilities;
+  for (const forbidden of [
+    "managed_delivery",
+    "reconciled_billing",
+    "receipt_task",
+    "readiness_notification",
+    "status_notification",
+    "ledger_notification",
+    "supports_webhook_activity"
+  ]) {
+    if (capabilities[forbidden] !== void 0) {
+      throw new Error(`Reliable Reporting Core must not advertise ${forbidden}`);
+    }
+  }
+  if (capabilities.consumer_status_task !== void 0 !== (service.platform.syncReportingStatus !== void 0)) {
+    throw new Error("Reliable reporting consumer-status capability does not match its installed handler");
+  }
+  if (capabilities.consumer_mismatch_escalation_seconds !== void 0 && capabilities.consumer_status_task !== "sync_reporting_status") {
+    throw new Error("Reliable reporting mismatch escalation requires the consumer-status task");
+  }
+  if (capabilities.status_task !== "get_reporting_status" || capabilities.revision_content_task !== "get_media_buy_delivery") {
+    throw new Error("Reliable reporting capability does not match its installed read handlers");
+  }
+}
+export {
+  runReliableReportingServiceConformanceV1
+};

package/dist/lib/reporting/service/index.d.mts

@@ -0,0 +1,182 @@
+import type { Account } from '../../server/decisioning/account.mjs';
+import type { RequestContext } from '../../server/decisioning/context.mjs';
+import type { DecisioningPlatform } from '../../server/decisioning/platform.mjs';
+import type { ReliableReportingPlatform } from '../../server/decisioning/specialisms/reporting.mjs';
+import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '../../types/tools.generated.mjs';
+import { REPORTING_LEDGER_MIGRATION, type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingSourceWithReaderV1 } from '../ledger/index.mjs';
+import type { InlineReportingReplayRetentionV1 } from '../source/index.mjs';
+import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source/index.mjs';
+/** The intentionally small provider boundary: one bounded slice fetch plus immutable metadata. */
+export interface ReliableReportingAdapterV1 {
+    readonly sourceOffering: ReportingSourceOfferingV1;
+    readonly deliveryOffering: ReportingDeliveryOffering;
+    /**
+     * Adapted through the bounded inline executor, which retains every admitted
+     * execution so an admitted key stays replayable — and therefore caps a scope
+     * at 100 slices. A scheduled feed that outlives that ceiling must supply
+     * `executor`, or opt in to `inlineReplayRetention`; without one of those it
+     * terminalizes with QUOTA_EXHAUSTED and does not recover.
+     */
+    readonly fetchSlice?: InlineReportingDeliveryFetchV1;
+    /**
+     * Explicit bounded replay window for the inline executor. Trades the lifetime
+     * replay guarantee for a feed that keeps producing; never applied silently.
+     */
+    readonly inlineReplayRetention?: InlineReportingReplayRetentionV1;
+    /**
+     * Escape hatch for feeds the inline executor cannot serve: pagination,
+     * durable staged objects, or replay that must survive process restarts.
+     * Mutually exclusive with `fetchSlice`.
+     */
+    readonly executor?: ReportingSourceWithReaderV1;
+}
+/**
+ * The media-buy/package denominator this account's credential is authorized to
+ * report on. `mediaBuyIds` is always derived from `constituents`, so the two
+ * can never disagree.
+ */
+export interface ReliableReportingCoverageV1 {
+    constituents: ReportingLedgerConfigurationV1['constituents'];
+}
+export interface ReliableReportingSourceRouteV1 {
+    /** Key in `adapters`; selected by trusted host code, never by buyer input. */
+    adapterId: string;
+    /** Durable non-secret upstream identifiers used to re-derive authorization per request. */
+    sourceScope: Record<string, unknown>;
+    /** Trusted upstream reporting clock for this account/scope. */
+    sourceTimezone: string;
+}
+type LedgerInstallInput = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'account' | 'sourceScope' | 'sourceTimezone' | 'sourceSettings' | 'contract' | 'constituents' | 'mediaBuyIds'>;
+/**
+ * Seller-resolved configuration facts. `currency`, account identity, source
+ * scope, timezone, and source contract are deliberately absent.
+ */
+export interface ReliableReportingConfigurationInputV1 extends LedgerInstallInput {
+    sourceSettings: Omit<ReportingLedgerConfigurationV1['sourceSettings'], 'currency'>;
+    /** Optional assertion from the commercial flow; disagreement fails closed. */
+    expectedCurrency?: string;
+    /** Optional assertion from account setup; disagreement fails closed. */
+    expectedSourceTimezone?: string;
+    /** Optional assertion of the requested media-buy scope; disagreement fails closed. */
+    expectedMediaBuyIds?: readonly string[];
+}
+export interface ReliableReportingInstallContextV1<TCtxMeta = Record<string, unknown>> {
+    /** Must be the framework-resolved account from RequestContext. */
+    account: Pick<Account<TCtxMeta>, 'id' | 'ctx_metadata'>;
+}
+interface ReliableReportingSchedulerBaseOptionsV1 {
+    intervalMilliseconds: number;
+    maxObligationsPerAccount?: number;
+    maxWorkerIterationsPerAccount?: number;
+    retryDelayMilliseconds?: number;
+    executionDeadlineMilliseconds?: number;
+    settlementGraceMilliseconds?: number;
+    onError?: (error: unknown) => void | Promise<void>;
+    /**
+     * Destination for the scheduler's own warn-level diagnostics. Defaults to
+     * `console.warn`.
+     *
+     * The scheduler is a durable background loop: a roster resolver that keeps
+     * throwing runs zero tenants every interval, and a tenant whose cycle keeps
+     * failing produces nothing, in both cases indefinitely and by design — the
+     * loop must not die. That makes silence the dangerous outcome, so a failure
+     * no `onError` was configured to observe is warned here instead of dropped.
+     *
+     * A configured `onError` owns reporting and nothing is warned alongside it,
+     * so an adopter's own pipeline is never duplicated. The one exception is an
+     * `onError` that itself throws: it would otherwise take both its own failure
+     * and the one it was handed down with it.
+     *
+     * Messages carry the failure phase, the account when there is one, and the
+     * error's `message` passed through credential redaction — never a stack,
+     * never the error object. Pass `{ warn: () => {} }` to opt out entirely.
+     */
+    logger?: {
+        warn: (message: string) => void;
+    };
+}
+export type ReliableReportingSchedulerOptionsV1 = ReliableReportingSchedulerBaseOptionsV1 & ({
+    deploymentWide: true;
+    accountIds?: never;
+} | {
+    deploymentWide?: false;
+    accountIds: readonly string[] | (() => readonly string[] | Promise<readonly string[]>);
+});
+interface ReliableReportingCycleBaseOptionsV1 {
+    now?: Date;
+    maxObligations?: number;
+    maxWorkerIterations?: number;
+    retryDelayMilliseconds?: number;
+    executionDeadlineMilliseconds?: number;
+    settlementGraceMilliseconds?: number;
+    signal?: AbortSignal;
+}
+export type ReliableReportingCycleOptionsV1 = ReliableReportingCycleBaseOptionsV1 & ({
+    deploymentWide: true;
+    accountId?: never;
+} | {
+    deploymentWide?: false;
+    accountId: string;
+});
+export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<string, unknown>> {
+    store: ReportingLedgerStore;
+    adapters: Readonly<Record<string, ReliableReportingAdapterV1>>;
+    contact: ReportingProducerContactV1;
+    resolveSource(account: Pick<Account<TCtxMeta>, 'id' | 'ctx_metadata'>, configuration: Readonly<ReliableReportingConfigurationInputV1>): ReliableReportingSourceRouteV1 | Promise<ReliableReportingSourceRouteV1>;
+    resolveCurrency(account: Pick<Account<TCtxMeta>, 'id' | 'ctx_metadata'>, configuration: Readonly<ReliableReportingConfigurationInputV1>): string | Promise<string>;
+    /**
+     * Authorize and derive the media-buy/package denominator for this account.
+     *
+     * This is an authorization boundary, not a convenience: `sourceScope` may
+     * legitimately resolve to a shared upstream network, so the constituent list
+     * is the only thing separating one buyer's orders from another's on that
+     * network. It must be derived from the resolved account, never echoed from
+     * the buyer's declaration.
+     */
+    resolveCoverage(account: Pick<Account<TCtxMeta>, 'id' | 'ctx_metadata'>, configuration: Readonly<ReliableReportingConfigurationInputV1>): ReliableReportingCoverageV1 | Promise<ReliableReportingCoverageV1>;
+    /** Enables authenticated consumer-scoped status reads and sync_reporting_status. */
+    resolveConsumerId?: (context: RequestContext<Account<TCtxMeta>>) => string | Promise<string>;
+    consumerMismatchEscalation?: ReportingConsumerMismatchEscalationV1;
+    automatedRecoveryWindowSeconds: number;
+    /** Ledger metadata retention commitment advertised to buyers. */
+    statusRetentionDays: number;
+    subscribers?: CreateReportingProducerOptionsV1['subscribers'];
+}
+export interface ReliableReportingSetupV1 {
+    readonly component: 'reliable-reporting-core';
+    readonly migrations: readonly [typeof REPORTING_LEDGER_MIGRATION];
+    readonly requiresIsolatedLedgerDatabaseAcknowledgement: true;
+}
+export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>> {
+    readonly setup: ReliableReportingSetupV1;
+    readonly capabilities: ReportingDeliveryCapabilities;
+    readonly producer: ReportingProducerV1;
+    readonly platform: ReliableReportingPlatform<TCtxMeta>;
+    readonly running: boolean;
+    installConfiguration(configuration: ReliableReportingConfigurationInputV1, context: ReliableReportingInstallContextV1<TCtxMeta>): Promise<ReportingLedgerConfigurationV1>;
+    /**
+     * Returns the same platform object, narrowed to also carry `reporting`.
+     * The input type is preserved: widening to `DecisioningPlatform` would erase
+     * literal `capabilities.specialisms` and adopter-declared members, and
+     * `createAdcpServerFromPlatform` enforces specialism-required tools off
+     * exactly those types.
+     */
+    install<TPlatform extends DecisioningPlatform<any, TCtxMeta>>(platform: TPlatform): TPlatform & {
+        reporting: ReliableReportingPlatform<TCtxMeta>;
+    };
+    runCycle(options: ReliableReportingCycleOptionsV1): Promise<{
+        planned: number;
+        claimed: number;
+        revisionsCommitted: number;
+        notReady: number;
+        failed: number;
+    }>;
+    start(options: ReliableReportingSchedulerOptionsV1): void;
+    stop(): Promise<void>;
+}
+/**
+ * Compose the existing source executor, ledger producer, protocol handlers,
+ * and scheduler into one Reliable Reporting Core lifecycle owner.
+ */
+export declare function createReliableReportingService<TCtxMeta = Record<string, unknown>>(options: CreateReliableReportingServiceOptionsV1<TCtxMeta>): ReliableReportingServiceV1<TCtxMeta>;
+export * from './conformance.mjs';

package/dist/lib/reporting/service/index.d.ts

@@ -0,0 +1,182 @@
+import type { Account } from '../../server/decisioning/account';
+import type { RequestContext } from '../../server/decisioning/context';
+import type { DecisioningPlatform } from '../../server/decisioning/platform';
+import type { ReliableReportingPlatform } from '../../server/decisioning/specialisms/reporting';
+import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '../../types/tools.generated';
+import { REPORTING_LEDGER_MIGRATION, type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingSourceWithReaderV1 } from '../ledger';
+import type { InlineReportingReplayRetentionV1 } from '../source';
+import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source';
+/** The intentionally small provider boundary: one bounded slice fetch plus immutable metadata. */
+export interface ReliableReportingAdapterV1 {
+    readonly sourceOffering: ReportingSourceOfferingV1;
+    readonly deliveryOffering: ReportingDeliveryOffering;
+    /**
+     * Adapted through the bounded inline executor, which retains every admitted
+     * execution so an admitted key stays replayable — and therefore caps a scope
+     * at 100 slices. A scheduled feed that outlives that ceiling must supply
+     * `executor`, or opt in to `inlineReplayRetention`; without one of those it
+     * terminalizes with QUOTA_EXHAUSTED and does not recover.
+     */
+    readonly fetchSlice?: InlineReportingDeliveryFetchV1;
+    /**
+     * Explicit bounded replay window for the inline executor. Trades the lifetime
+     * replay guarantee for a feed that keeps producing; never applied silently.
+     */
+    readonly inlineReplayRetention?: InlineReportingReplayRetentionV1;
+    /**
+     * Escape hatch for feeds the inline executor cannot serve: pagination,
+     * durable staged objects, or replay that must survive process restarts.
+     * Mutually exclusive with `fetchSlice`.
+     */
+    readonly executor?: ReportingSourceWithReaderV1;
+}
+/**
+ * The media-buy/package denominator this account's credential is authorized to
+ * report on. `mediaBuyIds` is always derived from `constituents`, so the two
+ * can never disagree.
+ */
+export interface ReliableReportingCoverageV1 {
+    constituents: ReportingLedgerConfigurationV1['constituents'];
+}
+export interface ReliableReportingSourceRouteV1 {
+    /** Key in `adapters`; selected by trusted host code, never by buyer input. */
+    adapterId: string;
+    /** Durable non-secret upstream identifiers used to re-derive authorization per request. */
+    sourceScope: Record<string, unknown>;
+    /** Trusted upstream reporting clock for this account/scope. */
+    sourceTimezone: string;
+}
+type LedgerInstallInput = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'account' | 'sourceScope' | 'sourceTimezone' | 'sourceSettings' | 'contract' | 'constituents' | 'mediaBuyIds'>;
+/**
+ * Seller-resolved configuration facts. `currency`, account identity, source
+ * scope, timezone, and source contract are deliberately absent.
+ */
+export interface ReliableReportingConfigurationInputV1 extends LedgerInstallInput {
+    sourceSettings: Omit<ReportingLedgerConfigurationV1['sourceSettings'], 'currency'>;
+    /** Optional assertion from the commercial flow; disagreement fails closed. */
+    expectedCurrency?: string;
+    /** Optional assertion from account setup; disagreement fails closed. */
+    expectedSourceTimezone?: string;
+    /** Optional assertion of the requested media-buy scope; disagreement fails closed. */
+    expectedMediaBuyIds?: readonly string[];
+}
+export interface ReliableReportingInstallContextV1<TCtxMeta = Record<string, unknown>> {
+    /** Must be the framework-resolved account from RequestContext. */
+    account: Pick<Account<TCtxMeta>, 'id' | 'ctx_metadata'>;
+}
+interface ReliableReportingSchedulerBaseOptionsV1 {
+    intervalMilliseconds: number;
+    maxObligationsPerAccount?: number;
+    maxWorkerIterationsPerAccount?: number;
+    retryDelayMilliseconds?: number;
+    executionDeadlineMilliseconds?: number;
+    settlementGraceMilliseconds?: number;
+    onError?: (error: unknown) => void | Promise<void>;
+    /**
+     * Destination for the scheduler's own warn-level diagnostics. Defaults to
+     * `console.warn`.
+     *
+     * The scheduler is a durable background loop: a roster resolver that keeps
+     * throwing runs zero tenants every interval, and a tenant whose cycle keeps
+     * failing produces nothing, in both cases indefinitely and by design — the
+     * loop must not die. That makes silence the dangerous outcome, so a failure
+     * no `onError` was configured to observe is warned here instead of dropped.
+     *
+     * A configured `onError` owns reporting and nothing is warned alongside it,
+     * so an adopter's own pipeline is never duplicated. The one exception is an
+     * `onError` that itself throws: it would otherwise take both its own failure
+     * and the one it was handed down with it.
+     *
+     * Messages carry the failure phase, the account when there is one, and the
+     * error's `message` passed through credential redaction — never a stack,
+     * never the error object. Pass `{ warn: () => {} }` to opt out entirely.
+     */
+    logger?: {
+        warn: (message: string) => void;
+    };
+}
+export type ReliableReportingSchedulerOptionsV1 = ReliableReportingSchedulerBaseOptionsV1 & ({
+    deploymentWide: true;
+    accountIds?: never;
+} | {
+    deploymentWide?: false;
+    accountIds: readonly string[] | (() => readonly string[] | Promise<readonly string[]>);
+});
+interface ReliableReportingCycleBaseOptionsV1 {
+    now?: Date;
+    maxObligations?: number;
+    maxWorkerIterations?: number;
+    retryDelayMilliseconds?: number;
+    executionDeadlineMilliseconds?: number;
+    settlementGraceMilliseconds?: number;
+    signal?: AbortSignal;
+}
+export type ReliableReportingCycleOptionsV1 = ReliableReportingCycleBaseOptionsV1 & ({
+    deploymentWide: true;
+    accountId?: never;
+} | {
+    deploymentWide?: false;
+    accountId: string;
+});
+export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<string, unknown>> {
+    store: ReportingLedgerStore;
+    adapters: Readonly<Record<string, ReliableReportingAdapterV1>>;
+    contact: ReportingProducerContactV1;
+    resolveSource(account: Pick<Account<TCtxMeta>, 'id' | 'ctx_metadata'>, configuration: Readonly<ReliableReportingConfigurationInputV1>): ReliableReportingSourceRouteV1 | Promise<ReliableReportingSourceRouteV1>;
+    resolveCurrency(account: Pick<Account<TCtxMeta>, 'id' | 'ctx_metadata'>, configuration: Readonly<ReliableReportingConfigurationInputV1>): string | Promise<string>;
+    /**
+     * Authorize and derive the media-buy/package denominator for this account.
+     *
+     * This is an authorization boundary, not a convenience: `sourceScope` may
+     * legitimately resolve to a shared upstream network, so the constituent list
+     * is the only thing separating one buyer's orders from another's on that
+     * network. It must be derived from the resolved account, never echoed from
+     * the buyer's declaration.
+     */
+    resolveCoverage(account: Pick<Account<TCtxMeta>, 'id' | 'ctx_metadata'>, configuration: Readonly<ReliableReportingConfigurationInputV1>): ReliableReportingCoverageV1 | Promise<ReliableReportingCoverageV1>;
+    /** Enables authenticated consumer-scoped status reads and sync_reporting_status. */
+    resolveConsumerId?: (context: RequestContext<Account<TCtxMeta>>) => string | Promise<string>;
+    consumerMismatchEscalation?: ReportingConsumerMismatchEscalationV1;
+    automatedRecoveryWindowSeconds: number;
+    /** Ledger metadata retention commitment advertised to buyers. */
+    statusRetentionDays: number;
+    subscribers?: CreateReportingProducerOptionsV1['subscribers'];
+}
+export interface ReliableReportingSetupV1 {
+    readonly component: 'reliable-reporting-core';
+    readonly migrations: readonly [typeof REPORTING_LEDGER_MIGRATION];
+    readonly requiresIsolatedLedgerDatabaseAcknowledgement: true;
+}
+export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>> {
+    readonly setup: ReliableReportingSetupV1;
+    readonly capabilities: ReportingDeliveryCapabilities;
+    readonly producer: ReportingProducerV1;
+    readonly platform: ReliableReportingPlatform<TCtxMeta>;
+    readonly running: boolean;
+    installConfiguration(configuration: ReliableReportingConfigurationInputV1, context: ReliableReportingInstallContextV1<TCtxMeta>): Promise<ReportingLedgerConfigurationV1>;
+    /**
+     * Returns the same platform object, narrowed to also carry `reporting`.
+     * The input type is preserved: widening to `DecisioningPlatform` would erase
+     * literal `capabilities.specialisms` and adopter-declared members, and
+     * `createAdcpServerFromPlatform` enforces specialism-required tools off
+     * exactly those types.
+     */
+    install<TPlatform extends DecisioningPlatform<any, TCtxMeta>>(platform: TPlatform): TPlatform & {
+        reporting: ReliableReportingPlatform<TCtxMeta>;
+    };
+    runCycle(options: ReliableReportingCycleOptionsV1): Promise<{
+        planned: number;
+        claimed: number;
+        revisionsCommitted: number;
+        notReady: number;
+        failed: number;
+    }>;
+    start(options: ReliableReportingSchedulerOptionsV1): void;
+    stop(): Promise<void>;
+}
+/**
+ * Compose the existing source executor, ledger producer, protocol handlers,
+ * and scheduler into one Reliable Reporting Core lifecycle owner.
+ */
+export declare function createReliableReportingService<TCtxMeta = Record<string, unknown>>(options: CreateReliableReportingServiceOptionsV1<TCtxMeta>): ReliableReportingServiceV1<TCtxMeta>;
+export * from './conformance';