@adcp/sdk 15.8.1 → 15.9.0

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

@@ -3,11 +3,38 @@ import type { AdcpToolMap } from '../../server/create-adcp-server.mjs';
 import { createReportingDeliveryHandler, createReportingStatusHandler } from './handler.mjs';
 import type { ReportingStatusConsumerScopeOptionsV1 } from './handler.mjs';
 import type { ReportingLedgerAdjustmentV1, ReportingLegacyRevisionReaderV1, ReportingLedgerObligationV1, ReportingLedgerRevisionV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1 } from './types.mjs';
+/**
+ * Upper bound on an adapter's startup probe, so a hung provider cannot hang startup.
+ * A router's per-route probe budget must stay under it, or this deadline fires
+ * first and the failing route's id never reaches the startup error.
+ */
+export declare const REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1 = 30000;
+/** The delivery pattern a destination authorization generation serves. */
+export type ReportingDestinationPatternV1 = ReportingManagedDeliveryBindingV1['method'];
+/** Delivery patterns, in the order the protocol lists them. */
+export declare const REPORTING_DESTINATION_PATTERNS_V1: readonly ReportingDestinationPatternV1[];
+/** Same constraint the protocol puts on `method.transport`. */
+export declare const REPORTING_DESTINATION_TRANSPORT_PATTERN_V1: RegExp;
 export interface ReportingDestinationAuthorizationV1 {
     account_id: string;
     destination_ref: string;
     generation: number;
     authorized_at: string;
+    /**
+     * Delivery pattern this generation serves, recorded when the generation is
+     * created. A destination has exactly one pattern, and a change to its
+     * delivery contract mints a new `destination_ref` generation, so this never
+     * changes for a generation. Absent on generations recorded before it
+     * existed (and on ones whose bindings did not agree when backfilled).
+     */
+    pattern?: ReportingDestinationPatternV1;
+    /**
+     * Transport (`s3`, `gcs`, ...) that holds this generation's provider grant,
+     * recorded and immutable like `pattern`. This is what lets `revoke()` be
+     * routed to the transport that holds the grant. Absent for the same legacy
+     * reasons as `pattern`.
+     */
+    transport?: string;
     revoked_at?: string;
     cleanup_completed_at?: string;
 }
@@ -123,6 +150,18 @@ export interface ReportingManagedDeliveryStore {
     installBinding(binding: ReportingManagedDeliveryBindingV1): Promise<{
         inserted: boolean;
     }>;
+    /**
+     * Installs the check `installBinding` applies to every new binding before it
+     * writes anything. A thrown error refuses the install and reaches the caller
+     * as-is. Pass `undefined` to remove it.
+     *
+     * The runtime registers the adapter's `admitBinding` here, so a binding no
+     * installed delivery route can serve is refused at install instead of
+     * failing at its first delivery. Optional on the structural interface so
+     * existing custom stores stay source-compatible; a runtime whose adapter
+     * supplies `admitBinding` refuses a store that cannot enforce it.
+     */
+    setBindingAdmission?(admit: ((binding: ReportingManagedDeliveryBindingV1) => void) | undefined): void;
     planMaterializations(input?: {
         account_id?: string;
         limit?: number;
@@ -236,6 +275,73 @@ export interface ReportingManagedDeliveryAdapterV1 {
     }>, context: {
         signal: AbortSignal;
     }): Promise<void>;
+    /**
+     * Optional startup check that the adapter can reach what it delivers to.
+     * The runtime calls it once, before it adopts any durable policy, and
+     * refuses to start if it rejects. It must not mutate provider state.
+     */
+    probe?(context: {
+        signal: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Optional install-time admission. Throw to refuse a binding this adapter
+     * could not deliver. The runtime wires it into the store's `installBinding`.
+     * A single adapter has no reason to define it; the delivery router does.
+     */
+    admitBinding?(binding: ReportingManagedDeliveryBindingV1): void;
+    /**
+     * Optional startup admission for an advertised managed offering. Throw if
+     * the adapter has no way to serve it. Called once per offering at runtime
+     * construction.
+     */
+    admitOffering?(offering: {
+        method: {
+            pattern: string;
+            transport: string;
+        };
+        reconciliation_mode?: string;
+    }): void;
+    /**
+     * Optional observability hook: the id of the route a binding or an
+     * authorization is dispatched to, or `undefined` if none. Only the id may be
+     * returned. The worker keys its per-route counts on it, so it must never
+     * carry credentials, locations or any other provider detail.
+     */
+    routeIdFor?(target: Readonly<{
+        binding: ReportingManagedDeliveryBindingV1;
+    } | {
+        authorization: ReportingDestinationAuthorizationV1;
+    }>): string | undefined;
+}
+/**
+ * Per-route counts keyed by delivery route id. Present on a worker result only
+ * when the installed adapter is a router, so a single-adapter runtime's result
+ * shape is unchanged. Work that no route could take is counted under
+ * `UNROUTED_REPORTING_ROUTE_KEY_V1`, which no route id can equal.
+ */
+export interface ReportingManagedDeliveryRouteCountsV1 {
+    /** Materializations settled as delivered, by the route that delivered them. */
+    deliveriesByRoute: Record<string, number>;
+    /** Materializations that failed (including an unroutable binding), by route. */
+    deliveryFailuresByRoute: Record<string, number>;
+    /** Provider revocations completed, by the route that performed them. */
+    revocationsByRoute: Record<string, number>;
+    /** Revocation attempts that failed and were released for retry, by route. */
+    revocationFailuresByRoute: Record<string, number>;
+    /** Revocations that had already outlived the advertised window when claimed, by route. */
+    overdueByRoute: Record<string, number>;
+}
+/** Key for work no delivery route could take. Not a valid route id. */
+export declare const UNROUTED_REPORTING_ROUTE_KEY_V1 = "~unrouted";
+export interface ReportingManagedDeliveryWorkerResultV1 extends Partial<ReportingManagedDeliveryRouteCountsV1> {
+    planned: number;
+    claimed: number;
+    delivered: number;
+    failed: number;
+    revocationsCompleted: number;
+    revocationsOverdue: number;
+    /** Materializations failed for using every delivery attempt. */
+    exhausted: number;
 }
 export interface ReportingManagedDeliveryWorkerOptionsV1 {
     signal?: AbortSignal;
@@ -297,16 +403,7 @@ export interface ReportingManagedDeliveryRuntimeV1<TContext extends {
     syncReportingReceipts?: (request: AdcpToolMap['sync_reporting_receipts']['params'], context: TContext & {
         account?: unknown;
     }) => Promise<SyncReportingReceiptsResponse>;
-    runWorker(options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<{
-        planned: number;
-        claimed: number;
-        delivered: number;
-        failed: number;
-        revocationsCompleted: number;
-        revocationsOverdue: number;
-        /** Materializations failed for using every delivery attempt. */
-        exhausted: number;
-    }>;
+    runWorker(options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<ReportingManagedDeliveryWorkerResultV1>;
     readResource(input: {
         account_id: string;
         resource_ref: string;
@@ -328,15 +425,7 @@ export declare function createReportingManagedDeliveryRuntime<TContext extends {
 export declare function createSyncReportingReceiptsHandler<TContext extends {
     account?: unknown;
 }>(store: ReportingManagedDeliveryStore, resolveConsumerId: (context: TContext) => string | Promise<string>, now?: () => Date): (request: AdcpToolMap["sync_reporting_receipts"]["params"], context: TContext) => Promise<SyncReportingReceiptsResponse>;
-export declare function runManagedDeliveryWorker(store: ReportingManagedDeliveryStore, adapter: ReportingManagedDeliveryAdapterV1, options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<{
-    exhausted: number;
-    planned: number;
-    claimed: number;
-    delivered: number;
-    failed: number;
-    revocationsCompleted: number;
-    revocationsOverdue: number;
-}>;
+export declare function runManagedDeliveryWorker(store: ReportingManagedDeliveryStore, adapter: ReportingManagedDeliveryAdapterV1, options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<ReportingManagedDeliveryWorkerResultV1>;
 export declare function readManagedReportingResource(store: ReportingManagedDeliveryStore, adapter: ReportingManagedDeliveryAdapterV1, input: {
     account_id: string;
     resource_ref: string;

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

@@ -3,11 +3,38 @@ import type { AdcpToolMap } from '../../server/create-adcp-server';
 import { createReportingDeliveryHandler, createReportingStatusHandler } from './handler';
 import type { ReportingStatusConsumerScopeOptionsV1 } from './handler';
 import type { ReportingLedgerAdjustmentV1, ReportingLegacyRevisionReaderV1, ReportingLedgerObligationV1, ReportingLedgerRevisionV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1 } from './types';
+/**
+ * Upper bound on an adapter's startup probe, so a hung provider cannot hang startup.
+ * A router's per-route probe budget must stay under it, or this deadline fires
+ * first and the failing route's id never reaches the startup error.
+ */
+export declare const REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1 = 30000;
+/** The delivery pattern a destination authorization generation serves. */
+export type ReportingDestinationPatternV1 = ReportingManagedDeliveryBindingV1['method'];
+/** Delivery patterns, in the order the protocol lists them. */
+export declare const REPORTING_DESTINATION_PATTERNS_V1: readonly ReportingDestinationPatternV1[];
+/** Same constraint the protocol puts on `method.transport`. */
+export declare const REPORTING_DESTINATION_TRANSPORT_PATTERN_V1: RegExp;
 export interface ReportingDestinationAuthorizationV1 {
     account_id: string;
     destination_ref: string;
     generation: number;
     authorized_at: string;
+    /**
+     * Delivery pattern this generation serves, recorded when the generation is
+     * created. A destination has exactly one pattern, and a change to its
+     * delivery contract mints a new `destination_ref` generation, so this never
+     * changes for a generation. Absent on generations recorded before it
+     * existed (and on ones whose bindings did not agree when backfilled).
+     */
+    pattern?: ReportingDestinationPatternV1;
+    /**
+     * Transport (`s3`, `gcs`, ...) that holds this generation's provider grant,
+     * recorded and immutable like `pattern`. This is what lets `revoke()` be
+     * routed to the transport that holds the grant. Absent for the same legacy
+     * reasons as `pattern`.
+     */
+    transport?: string;
     revoked_at?: string;
     cleanup_completed_at?: string;
 }
@@ -123,6 +150,18 @@ export interface ReportingManagedDeliveryStore {
     installBinding(binding: ReportingManagedDeliveryBindingV1): Promise<{
         inserted: boolean;
     }>;
+    /**
+     * Installs the check `installBinding` applies to every new binding before it
+     * writes anything. A thrown error refuses the install and reaches the caller
+     * as-is. Pass `undefined` to remove it.
+     *
+     * The runtime registers the adapter's `admitBinding` here, so a binding no
+     * installed delivery route can serve is refused at install instead of
+     * failing at its first delivery. Optional on the structural interface so
+     * existing custom stores stay source-compatible; a runtime whose adapter
+     * supplies `admitBinding` refuses a store that cannot enforce it.
+     */
+    setBindingAdmission?(admit: ((binding: ReportingManagedDeliveryBindingV1) => void) | undefined): void;
     planMaterializations(input?: {
         account_id?: string;
         limit?: number;
@@ -236,6 +275,73 @@ export interface ReportingManagedDeliveryAdapterV1 {
     }>, context: {
         signal: AbortSignal;
     }): Promise<void>;
+    /**
+     * Optional startup check that the adapter can reach what it delivers to.
+     * The runtime calls it once, before it adopts any durable policy, and
+     * refuses to start if it rejects. It must not mutate provider state.
+     */
+    probe?(context: {
+        signal: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Optional install-time admission. Throw to refuse a binding this adapter
+     * could not deliver. The runtime wires it into the store's `installBinding`.
+     * A single adapter has no reason to define it; the delivery router does.
+     */
+    admitBinding?(binding: ReportingManagedDeliveryBindingV1): void;
+    /**
+     * Optional startup admission for an advertised managed offering. Throw if
+     * the adapter has no way to serve it. Called once per offering at runtime
+     * construction.
+     */
+    admitOffering?(offering: {
+        method: {
+            pattern: string;
+            transport: string;
+        };
+        reconciliation_mode?: string;
+    }): void;
+    /**
+     * Optional observability hook: the id of the route a binding or an
+     * authorization is dispatched to, or `undefined` if none. Only the id may be
+     * returned. The worker keys its per-route counts on it, so it must never
+     * carry credentials, locations or any other provider detail.
+     */
+    routeIdFor?(target: Readonly<{
+        binding: ReportingManagedDeliveryBindingV1;
+    } | {
+        authorization: ReportingDestinationAuthorizationV1;
+    }>): string | undefined;
+}
+/**
+ * Per-route counts keyed by delivery route id. Present on a worker result only
+ * when the installed adapter is a router, so a single-adapter runtime's result
+ * shape is unchanged. Work that no route could take is counted under
+ * `UNROUTED_REPORTING_ROUTE_KEY_V1`, which no route id can equal.
+ */
+export interface ReportingManagedDeliveryRouteCountsV1 {
+    /** Materializations settled as delivered, by the route that delivered them. */
+    deliveriesByRoute: Record<string, number>;
+    /** Materializations that failed (including an unroutable binding), by route. */
+    deliveryFailuresByRoute: Record<string, number>;
+    /** Provider revocations completed, by the route that performed them. */
+    revocationsByRoute: Record<string, number>;
+    /** Revocation attempts that failed and were released for retry, by route. */
+    revocationFailuresByRoute: Record<string, number>;
+    /** Revocations that had already outlived the advertised window when claimed, by route. */
+    overdueByRoute: Record<string, number>;
+}
+/** Key for work no delivery route could take. Not a valid route id. */
+export declare const UNROUTED_REPORTING_ROUTE_KEY_V1 = "~unrouted";
+export interface ReportingManagedDeliveryWorkerResultV1 extends Partial<ReportingManagedDeliveryRouteCountsV1> {
+    planned: number;
+    claimed: number;
+    delivered: number;
+    failed: number;
+    revocationsCompleted: number;
+    revocationsOverdue: number;
+    /** Materializations failed for using every delivery attempt. */
+    exhausted: number;
 }
 export interface ReportingManagedDeliveryWorkerOptionsV1 {
     signal?: AbortSignal;
@@ -297,16 +403,7 @@ export interface ReportingManagedDeliveryRuntimeV1<TContext extends {
     syncReportingReceipts?: (request: AdcpToolMap['sync_reporting_receipts']['params'], context: TContext & {
         account?: unknown;
     }) => Promise<SyncReportingReceiptsResponse>;
-    runWorker(options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<{
-        planned: number;
-        claimed: number;
-        delivered: number;
-        failed: number;
-        revocationsCompleted: number;
-        revocationsOverdue: number;
-        /** Materializations failed for using every delivery attempt. */
-        exhausted: number;
-    }>;
+    runWorker(options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<ReportingManagedDeliveryWorkerResultV1>;
     readResource(input: {
         account_id: string;
         resource_ref: string;
@@ -328,15 +425,7 @@ export declare function createReportingManagedDeliveryRuntime<TContext extends {
 export declare function createSyncReportingReceiptsHandler<TContext extends {
     account?: unknown;
 }>(store: ReportingManagedDeliveryStore, resolveConsumerId: (context: TContext) => string | Promise<string>, now?: () => Date): (request: AdcpToolMap["sync_reporting_receipts"]["params"], context: TContext) => Promise<SyncReportingReceiptsResponse>;
-export declare function runManagedDeliveryWorker(store: ReportingManagedDeliveryStore, adapter: ReportingManagedDeliveryAdapterV1, options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<{
-    exhausted: number;
-    planned: number;
-    claimed: number;
-    delivered: number;
-    failed: number;
-    revocationsCompleted: number;
-    revocationsOverdue: number;
-}>;
+export declare function runManagedDeliveryWorker(store: ReportingManagedDeliveryStore, adapter: ReportingManagedDeliveryAdapterV1, options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<ReportingManagedDeliveryWorkerResultV1>;
 export declare function readManagedReportingResource(store: ReportingManagedDeliveryStore, adapter: ReportingManagedDeliveryAdapterV1, input: {
     account_id: string;
     resource_ref: string;

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

@@ -18,6 +18,10 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var managed_exports = {};
 __export(managed_exports, {
+  REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1: () => REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1,
+  REPORTING_DESTINATION_PATTERNS_V1: () => REPORTING_DESTINATION_PATTERNS_V1,
+  REPORTING_DESTINATION_TRANSPORT_PATTERN_V1: () => REPORTING_DESTINATION_TRANSPORT_PATTERN_V1,
+  UNROUTED_REPORTING_ROUTE_KEY_V1: () => UNROUTED_REPORTING_ROUTE_KEY_V1,
   adjustmentReceiptEvidenceMatches: () => adjustmentReceiptEvidenceMatches,
   assertCredentialFreeReportingResourceLocationV1: () => assertCredentialFreeReportingResourceLocationV1,
   assertMaterializationOutcome: () => assertMaterializationOutcome,
@@ -40,12 +44,21 @@ const DEFAULT_LEASE_MILLISECONDS = 65e3;
 const DEFAULT_DELIVERY_DEADLINE_MILLISECONDS = 6e4;
 const MINIMUM_SETTLEMENT_GRACE_MILLISECONDS = 5e3;
 const DEFAULT_RESOURCE_MAX_BYTES = 64 * 1024 * 1024;
+const REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1 = 3e4;
+const ADAPTER_PROBE_DEADLINE_MILLISECONDS = REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1;
 const MAX_DESCRIPTOR_BYTES = 1024 * 1024;
 const MAX_NODE_TIMER_DELAY_MILLISECONDS = 2147483647;
 const NANOSECONDS_PER_MILLISECOND = 1000000n;
 const MAX_RECEIPTS_PER_ARRAY = 100;
 const MAX_RECEIPT_RESULTS = 100;
 const MAX_RECEIPT_EVIDENCE_BYTES = 64 * 1024;
+const REPORTING_DESTINATION_PATTERNS_V1 = Object.freeze([
+  "file_transfer",
+  "dataset_share",
+  "warehouse_materialization"
+]);
+const REPORTING_DESTINATION_TRANSPORT_PATTERN_V1 = /^[a-z][a-z0-9_.-]{0,63}$/;
+const UNROUTED_REPORTING_ROUTE_KEY_V1 = "~unrouted";
 async function createReportingManagedDeliveryRuntime(options) {
   if (!await options.store.probe(options.coreStore)) {
     throw new Error("Managed reporting store is not operational for the configured Core authority");
@@ -77,6 +90,18 @@ async function createReportingManagedDeliveryRuntime(options) {
       "Consumer-receipt offerings require an authenticated receipt handler and canonical-digest verifier"
     );
   }
+  if (typeof options.adapter.admitOffering === "function") {
+    for (const offering of options.offerings) {
+      const method = offering.method;
+      if (method === void 0) continue;
+      options.adapter.admitOffering({ method, reconciliation_mode: offering.reconciliation_mode });
+    }
+  }
+  if (typeof options.adapter.admitBinding === "function" && typeof options.store.setBindingAdmission !== "function") {
+    throw new Error(
+      "This Managed Delivery adapter admits bindings at install, but the store cannot enforce an install-time admission"
+    );
+  }
   const reconciledBilling = reconciledOfferings.length > 0;
   for (const offering of reconciledOfferings) {
     const profile = offering.reporting_profile;
@@ -114,6 +139,7 @@ async function createReportingManagedDeliveryRuntime(options) {
       `Managed Delivery capability wiring is invalid: ${parsedCapabilities.error.issues[0]?.message ?? "invalid"}`
     );
   }
+  if (typeof options.adapter.probe === "function") await probeAdapter(options.adapter);
   const adoptedPolicy = await options.store.adoptAdvertisedPolicies({
     automatedRecoveryWindowSeconds: options.automatedRecoveryWindowSeconds,
     statusRetentionDays: options.statusRetentionDays,
@@ -127,6 +153,10 @@ async function createReportingManagedDeliveryRuntime(options) {
   if (adoptedPolicy.automatedRecoveryWindowSeconds > options.automatedRecoveryWindowSeconds || adoptedPolicy.statusRetentionDays < options.statusRetentionDays || adoptedPolicy.resourceRetentionDays < options.resourceRetentionDays || adoptedPolicy.authorizationRevocationSeconds > options.authorizationRevocationSeconds) {
     throw new Error("Managed Delivery policy adoption returned values weaker than the capability being published");
   }
+  if (typeof options.adapter.admitBinding === "function") {
+    const adapter = options.adapter;
+    options.store.setBindingAdmission?.((binding) => adapter.admitBinding(binding));
+  }
   return {
     reportingDeliveryCapabilities,
     getReportingStatus,
@@ -321,6 +351,25 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
     revocationsCompleted: 0,
     revocationsOverdue: 0
   };
+  const routed = typeof adapter.routeIdFor === "function" ? {
+    deliveriesByRoute: {},
+    deliveryFailuresByRoute: {},
+    revocationsByRoute: {},
+    revocationFailuresByRoute: {},
+    overdueByRoute: {}
+  } : void 0;
+  if (routed) Object.assign(counts, routed);
+  const countRoute = (bucket, target) => {
+    if (!routed) return;
+    let id;
+    try {
+      id = adapter.routeIdFor(target);
+    } catch {
+      id = void 0;
+    }
+    const key = typeof id === "string" && id !== "" ? id : UNROUTED_REPORTING_ROUTE_KEY_V1;
+    routed[bucket][key] = (routed[bucket][key] ?? 0) + 1;
+  };
   for (let index = 0; index < maxIterations; index += 1) {
     options.signal?.throwIfAborted();
     const revocation = await store.claimRevocation({
@@ -339,7 +388,10 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
     if (!revocation) break;
     const remaining = revocation.remaining_milliseconds ?? remainingRevocationMilliseconds(revocation, revocationWindow, now());
     const overdue = revocation.overdue ?? (remaining !== void 0 && remaining <= 0);
-    if (overdue) counts.revocationsOverdue += 1;
+    if (overdue) {
+      counts.revocationsOverdue += 1;
+      countRoute("overdueByRoute", { authorization: revocation.authorization });
+    }
     const attemptDeadline = remaining !== void 0 && remaining > 0 ? Math.min(deadlineMilliseconds, remaining) : deadlineMilliseconds;
     try {
       await withinDeadline(
@@ -350,8 +402,10 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
       );
       if (await store.completeRevocation({ lease: revocation, completed_at: now().toISOString() })) {
         counts.revocationsCompleted += 1;
+        countRoute("revocationsByRoute", { authorization: revocation.authorization });
       }
     } catch {
+      countRoute("revocationFailuresByRoute", { authorization: revocation.authorization });
       await store.releaseRevocation({ lease: revocation });
     }
   }
@@ -401,9 +455,13 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
           lease.binding.resource_retention_days,
           minimumResourceRetentionDays
         )
-      }))
+      })) {
         counts.delivered += 1;
-      else counts.failed += 1;
+        countRoute("deliveriesByRoute", { binding: lease.binding });
+      } else {
+        counts.failed += 1;
+        countRoute("deliveryFailuresByRoute", { binding: lease.binding });
+      }
     } catch {
       await store.settleMaterialization({
         lease,
@@ -411,10 +469,27 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
         outcome: { status: "failed", failure_code: "DELIVERY_FAILED" }
       });
       counts.failed += 1;
+      countRoute("deliveryFailuresByRoute", { binding: lease.binding });
     }
   }
   return counts;
 }
+async function probeAdapter(adapter) {
+  try {
+    await withinDeadline(
+      (signal) => Promise.resolve().then(() => adapter.probe({ signal })),
+      ADAPTER_PROBE_DEADLINE_MILLISECONDS,
+      "Managed Delivery adapter probe deadline elapsed"
+    );
+  } catch (cause) {
+    const failed = cause?.failedRouteIds;
+    const routes = Array.isArray(failed) ? failed.filter((id) => typeof id === "string") : [];
+    throw new Error(
+      routes.length ? `Managed Delivery adapter probe failed for route ${routes.map((id) => JSON.stringify(id)).join(", ")}` : "Managed Delivery adapter probe failed",
+      { cause }
+    );
+  }
+}
 function remainingRevocationMilliseconds(revocation, revocationWindow, now) {
   if (revocationWindow === void 0) return void 0;
   const revokedAt = revocation.authorization.revoked_at;
@@ -670,6 +745,10 @@ function reportingManagedDeliveryBindingV1(input) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1,
+  REPORTING_DESTINATION_PATTERNS_V1,
+  REPORTING_DESTINATION_TRANSPORT_PATTERN_V1,
+  UNROUTED_REPORTING_ROUTE_KEY_V1,
   adjustmentReceiptEvidenceMatches,
   assertCredentialFreeReportingResourceLocationV1,
   assertMaterializationOutcome,

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

@@ -13,12 +13,21 @@ const DEFAULT_LEASE_MILLISECONDS = 65e3;
 const DEFAULT_DELIVERY_DEADLINE_MILLISECONDS = 6e4;
 const MINIMUM_SETTLEMENT_GRACE_MILLISECONDS = 5e3;
 const DEFAULT_RESOURCE_MAX_BYTES = 64 * 1024 * 1024;
+const REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1 = 3e4;
+const ADAPTER_PROBE_DEADLINE_MILLISECONDS = REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1;
 const MAX_DESCRIPTOR_BYTES = 1024 * 1024;
 const MAX_NODE_TIMER_DELAY_MILLISECONDS = 2147483647;
 const NANOSECONDS_PER_MILLISECOND = 1000000n;
 const MAX_RECEIPTS_PER_ARRAY = 100;
 const MAX_RECEIPT_RESULTS = 100;
 const MAX_RECEIPT_EVIDENCE_BYTES = 64 * 1024;
+const REPORTING_DESTINATION_PATTERNS_V1 = Object.freeze([
+  "file_transfer",
+  "dataset_share",
+  "warehouse_materialization"
+]);
+const REPORTING_DESTINATION_TRANSPORT_PATTERN_V1 = /^[a-z][a-z0-9_.-]{0,63}$/;
+const UNROUTED_REPORTING_ROUTE_KEY_V1 = "~unrouted";
 async function createReportingManagedDeliveryRuntime(options) {
   if (!await options.store.probe(options.coreStore)) {
     throw new Error("Managed reporting store is not operational for the configured Core authority");
@@ -50,6 +59,18 @@ async function createReportingManagedDeliveryRuntime(options) {
       "Consumer-receipt offerings require an authenticated receipt handler and canonical-digest verifier"
     );
   }
+  if (typeof options.adapter.admitOffering === "function") {
+    for (const offering of options.offerings) {
+      const method = offering.method;
+      if (method === void 0) continue;
+      options.adapter.admitOffering({ method, reconciliation_mode: offering.reconciliation_mode });
+    }
+  }
+  if (typeof options.adapter.admitBinding === "function" && typeof options.store.setBindingAdmission !== "function") {
+    throw new Error(
+      "This Managed Delivery adapter admits bindings at install, but the store cannot enforce an install-time admission"
+    );
+  }
   const reconciledBilling = reconciledOfferings.length > 0;
   for (const offering of reconciledOfferings) {
     const profile = offering.reporting_profile;
@@ -87,6 +108,7 @@ async function createReportingManagedDeliveryRuntime(options) {
       `Managed Delivery capability wiring is invalid: ${parsedCapabilities.error.issues[0]?.message ?? "invalid"}`
     );
   }
+  if (typeof options.adapter.probe === "function") await probeAdapter(options.adapter);
   const adoptedPolicy = await options.store.adoptAdvertisedPolicies({
     automatedRecoveryWindowSeconds: options.automatedRecoveryWindowSeconds,
     statusRetentionDays: options.statusRetentionDays,
@@ -100,6 +122,10 @@ async function createReportingManagedDeliveryRuntime(options) {
   if (adoptedPolicy.automatedRecoveryWindowSeconds > options.automatedRecoveryWindowSeconds || adoptedPolicy.statusRetentionDays < options.statusRetentionDays || adoptedPolicy.resourceRetentionDays < options.resourceRetentionDays || adoptedPolicy.authorizationRevocationSeconds > options.authorizationRevocationSeconds) {
     throw new Error("Managed Delivery policy adoption returned values weaker than the capability being published");
   }
+  if (typeof options.adapter.admitBinding === "function") {
+    const adapter = options.adapter;
+    options.store.setBindingAdmission?.((binding) => adapter.admitBinding(binding));
+  }
   return {
     reportingDeliveryCapabilities,
     getReportingStatus,
@@ -294,6 +320,25 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
     revocationsCompleted: 0,
     revocationsOverdue: 0
   };
+  const routed = typeof adapter.routeIdFor === "function" ? {
+    deliveriesByRoute: {},
+    deliveryFailuresByRoute: {},
+    revocationsByRoute: {},
+    revocationFailuresByRoute: {},
+    overdueByRoute: {}
+  } : void 0;
+  if (routed) Object.assign(counts, routed);
+  const countRoute = (bucket, target) => {
+    if (!routed) return;
+    let id;
+    try {
+      id = adapter.routeIdFor(target);
+    } catch {
+      id = void 0;
+    }
+    const key = typeof id === "string" && id !== "" ? id : UNROUTED_REPORTING_ROUTE_KEY_V1;
+    routed[bucket][key] = (routed[bucket][key] ?? 0) + 1;
+  };
   for (let index = 0; index < maxIterations; index += 1) {
     options.signal?.throwIfAborted();
     const revocation = await store.claimRevocation({
@@ -312,7 +357,10 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
     if (!revocation) break;
     const remaining = revocation.remaining_milliseconds ?? remainingRevocationMilliseconds(revocation, revocationWindow, now());
     const overdue = revocation.overdue ?? (remaining !== void 0 && remaining <= 0);
-    if (overdue) counts.revocationsOverdue += 1;
+    if (overdue) {
+      counts.revocationsOverdue += 1;
+      countRoute("overdueByRoute", { authorization: revocation.authorization });
+    }
     const attemptDeadline = remaining !== void 0 && remaining > 0 ? Math.min(deadlineMilliseconds, remaining) : deadlineMilliseconds;
     try {
       await withinDeadline(
@@ -323,8 +371,10 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
       );
       if (await store.completeRevocation({ lease: revocation, completed_at: now().toISOString() })) {
         counts.revocationsCompleted += 1;
+        countRoute("revocationsByRoute", { authorization: revocation.authorization });
       }
     } catch {
+      countRoute("revocationFailuresByRoute", { authorization: revocation.authorization });
       await store.releaseRevocation({ lease: revocation });
     }
   }
@@ -374,9 +424,13 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
           lease.binding.resource_retention_days,
           minimumResourceRetentionDays
         )
-      }))
+      })) {
         counts.delivered += 1;
-      else counts.failed += 1;
+        countRoute("deliveriesByRoute", { binding: lease.binding });
+      } else {
+        counts.failed += 1;
+        countRoute("deliveryFailuresByRoute", { binding: lease.binding });
+      }
     } catch {
       await store.settleMaterialization({
         lease,
@@ -384,10 +438,27 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
         outcome: { status: "failed", failure_code: "DELIVERY_FAILED" }
       });
       counts.failed += 1;
+      countRoute("deliveryFailuresByRoute", { binding: lease.binding });
     }
   }
   return counts;
 }
+async function probeAdapter(adapter) {
+  try {
+    await withinDeadline(
+      (signal) => Promise.resolve().then(() => adapter.probe({ signal })),
+      ADAPTER_PROBE_DEADLINE_MILLISECONDS,
+      "Managed Delivery adapter probe deadline elapsed"
+    );
+  } catch (cause) {
+    const failed = cause?.failedRouteIds;
+    const routes = Array.isArray(failed) ? failed.filter((id) => typeof id === "string") : [];
+    throw new Error(
+      routes.length ? `Managed Delivery adapter probe failed for route ${routes.map((id) => JSON.stringify(id)).join(", ")}` : "Managed Delivery adapter probe failed",
+      { cause }
+    );
+  }
+}
 function remainingRevocationMilliseconds(revocation, revocationWindow, now) {
   if (revocationWindow === void 0) return void 0;
   const revokedAt = revocation.authorization.revoked_at;
@@ -642,6 +713,10 @@ function reportingManagedDeliveryBindingV1(input) {
   return { ...semantic, created_at, semantic_fingerprint };
 }
 export {
+  REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1,
+  REPORTING_DESTINATION_PATTERNS_V1,
+  REPORTING_DESTINATION_TRANSPORT_PATTERN_V1,
+  UNROUTED_REPORTING_ROUTE_KEY_V1,
   adjustmentReceiptEvidenceMatches,
   assertCredentialFreeReportingResourceLocationV1,
   assertMaterializationOutcome,