@adcp/sdk 16.0.0-beta.2 → 16.0.0-beta.4

package/dist/lib/reporting/s3/index.mjs

@@ -1,340 +0,0 @@
-import { randomUUID } from "node:crypto";
-import {
-  DeleteObjectCommand,
-  GetBucketLifecycleConfigurationCommand,
-  GetBucketPolicyStatusCommand,
-  GetBucketVersioningCommand,
-  GetObjectCommand,
-  HeadBucketCommand,
-  HeadObjectCommand,
-  PutObjectCommand
-} from "@aws-sdk/client-s3";
-import { ReportingRowStoreError } from "../ledger/row-storage-errors.mjs";
-import {
-  assertReportingRowLocationKeys,
-  assertReportingRowReadBounds,
-  readReportingRowStream,
-  reportingRowClientMap,
-  reportingRowPrefixFilterOverlaps,
-  runReportingRowProviderOperation,
-  selectReportingRowClient
-} from "../ledger/row-storage-provider-io.mjs";
-const BUCKET = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
-const REGION = /^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$/;
-const VERSION_ID = /^[\x21\x23-\x7e]{1,1024}$/;
-function statusOf(error) {
-  const status = Number(error?.$metadata?.httpStatusCode);
-  return Number.isInteger(status) ? status : void 0;
-}
-function nameOf(error) {
-  const value = error?.name ?? error?.Code;
-  return typeof value === "string" ? value : "";
-}
-const isPreconditionFailed = (error) => statusOf(error) === 412 || nameOf(error) === "PreconditionFailed";
-const isConditionalConflict = (error) => statusOf(error) === 409 || nameOf(error) === "ConditionalRequestConflict";
-const isNotFound = (error) => statusOf(error) === 404 || ["NoSuchKey", "NotFound", "NoSuchVersion", "NoSuchBucket"].includes(nameOf(error));
-const isNotImplemented = (error) => statusOf(error) === 501 || nameOf(error) === "NotImplemented";
-const isForbidden = (error) => statusOf(error) === 401 || statusOf(error) === 403;
-const isRangeError = (error) => statusOf(error) === 416 || nameOf(error) === "InvalidRange";
-function versionOf(output) {
-  const id = output.VersionId;
-  if (typeof id !== "string" || id === "null" || !VERSION_ID.test(id)) {
-    throw new ReportingRowStoreError(
-      "UNSAFE_BINDING",
-      "store returned no object VersionId; S3 bucket versioning must be enabled so deletes are fenced to one write"
-    );
-  }
-  return id;
-}
-function selectorOf(nativeVersionRef) {
-  if (typeof nativeVersionRef !== "string" || nativeVersionRef === "null") return null;
-  return VERSION_ID.test(nativeVersionRef) ? { VersionId: nativeVersionRef } : null;
-}
-function servedVersion(output, selector) {
-  return output.VersionId === selector.VersionId;
-}
-function liveExpirationCovers(rule, prefix) {
-  if (rule.Status !== "Enabled") return false;
-  if (rule.Expiration?.Days === void 0 && rule.Expiration?.Date === void 0) return false;
-  if (rule.Filter?.Tag !== void 0 || (rule.Filter?.And?.Tags?.length ?? 0) > 0) return false;
-  const filter = rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? rule.Prefix;
-  return reportingRowPrefixFilterOverlaps(filter, prefix);
-}
-function createS3ReportingRowObjectProviderV1(options) {
-  if (!options || typeof options !== "object") {
-    throw new ReportingRowStoreError("INVALID_INPUT", "S3 row provider options are required");
-  }
-  const clients = reportingRowClientMap(options.clients);
-  const isClient = (value) => !!value && typeof value === "object" && typeof value.send === "function";
-  if (options.client !== void 0 && !isClient(options.client) || [...clients.values()].some((client) => !isClient(client)) || options.client === void 0 && clients.size === 0) {
-    throw new ReportingRowStoreError("INVALID_INPUT", "inject an official S3Client as client or clients");
-  }
-  const validateLocation = (location) => {
-    assertReportingRowLocationKeys(location, ["bucket"], ["region"]);
-    const bucket = location.bucket;
-    if (!BUCKET.test(bucket) || bucket.includes("..") || /^\d+\.\d+\.\d+\.\d+$/.test(bucket)) {
-      throw new ReportingRowStoreError("INVALID_INPUT", "S3 bucket name is invalid");
-    }
-    if (location.region !== void 0 && !REGION.test(location.region)) {
-      throw new ReportingRowStoreError("INVALID_INPUT", "S3 region is invalid");
-    }
-  };
-  const target = (input) => {
-    validateLocation(input.location);
-    return {
-      client: selectReportingRowClient(options.client, clients, input.credentialRef),
-      Bucket: input.location.bucket
-    };
-  };
-  const assertKey = (key) => {
-    if (typeof key !== "string" || key.length === 0 || Buffer.byteLength(key) > 1024) {
-      throw new ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
-    }
-  };
-  async function putCreateOnly(client, params, signal) {
-    for (let attempt = 0; ; attempt++) {
-      try {
-        return await client.send(new PutObjectCommand({ ...params, IfNoneMatch: "*" }), { abortSignal: signal });
-      } catch (error) {
-        if (attempt === 0 && isConditionalConflict(error) && !signal.aborted) continue;
-        throw error;
-      }
-    }
-  }
-  async function assertVersioningEnabled(client, Bucket, signal) {
-    let status;
-    try {
-      status = (await client.send(new GetBucketVersioningCommand({ Bucket }), { abortSignal: signal })).Status;
-    } catch (error) {
-      if (isForbidden(error) || isNotImplemented(error)) {
-        throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket versioning status cannot be verified");
-      }
-      throw error;
-    }
-    if (status !== "Enabled") {
-      throw new ReportingRowStoreError(
-        "UNSAFE_BINDING",
-        "S3 bucket versioning must be enabled so row object deletes are fenced to one write"
-      );
-    }
-  }
-  async function assertCreateOnlyEnforced(client, Bucket, prefix, signal) {
-    const Key = `${prefix}/.adcp-probe/${randomUUID()}`;
-    const written = [];
-    const put = async (body) => {
-      const output = await putCreateOnly(
-        client,
-        { Bucket, Key, Body: Buffer.from(body), ContentType: "application/x-ndjson", CacheControl: "no-store" },
-        signal
-      );
-      written.push(output);
-      versionOf(output);
-    };
-    try {
-      try {
-        await put('{"probe":1}\n');
-      } catch (error) {
-        if (isNotImplemented(error) || isPreconditionFailed(error)) {
-          throw new ReportingRowStoreError("UNSAFE_BINDING", "store does not support create-only writes");
-        }
-        throw error;
-      }
-      try {
-        await put('{"probe":2}\n');
-      } catch (error) {
-        if (isPreconditionFailed(error)) return;
-        if (isNotImplemented(error)) {
-          throw new ReportingRowStoreError("UNSAFE_BINDING", "store does not support create-only writes");
-        }
-        throw error;
-      }
-      throw new ReportingRowStoreError("UNSAFE_BINDING", "store ignores If-None-Match and replaces objects");
-    } finally {
-      const versionIds = written.map((output) => output.VersionId).filter((id) => !!id);
-      const deletes = versionIds.length > 0 ? versionIds.map((VersionId) => ({ VersionId })) : written.length ? [{}] : [];
-      for (const selector of deletes) {
-        if (signal.aborted) break;
-        await client.send(new DeleteObjectCommand({ Bucket, Key, ...selector }), { abortSignal: signal }).catch(() => void 0);
-      }
-    }
-  }
-  return {
-    name: "s3",
-    rangedReads: true,
-    validateLocation,
-    probe(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        const signal = context.signal;
-        try {
-          await client.send(new HeadBucketCommand({ Bucket }), { abortSignal: signal });
-        } catch (error) {
-          if (isNotFound(error)) throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket does not exist");
-          if (isForbidden(error)) throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket is not accessible");
-          if (statusOf(error) === 301) {
-            throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket is in a different region");
-          }
-          throw error;
-        }
-        if (input.location.region !== void 0) {
-          const configured = client.config?.region;
-          const region = typeof configured === "function" ? await configured() : configured;
-          if (region !== input.location.region) {
-            throw new ReportingRowStoreError("UNSAFE_BINDING", "client region does not match the binding");
-          }
-        }
-        const policy = await client.send(new GetBucketPolicyStatusCommand({ Bucket }), { abortSignal: signal }).catch(() => void 0);
-        if (policy?.PolicyStatus?.IsPublic === true) {
-          throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket policy makes objects public");
-        }
-        let rules = [];
-        try {
-          const lifecycle = await client.send(new GetBucketLifecycleConfigurationCommand({ Bucket }), {
-            abortSignal: signal
-          });
-          rules = lifecycle.Rules ?? [];
-        } catch (error) {
-          if (isForbidden(error)) {
-            throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket lifecycle cannot be read with this client");
-          }
-          if (!isNotFound(error) && !isNotImplemented(error) && nameOf(error) !== "NoSuchLifecycleConfiguration") {
-            throw error;
-          }
-        }
-        if (rules.some((rule) => liveExpirationCovers(rule, input.prefix))) {
-          throw new ReportingRowStoreError("UNSAFE_BINDING", "a bucket lifecycle rule can expire live row objects");
-        }
-        await assertVersioningEnabled(client, Bucket, signal);
-        await assertCreateOnlyEnforced(client, Bucket, input.prefix, signal);
-      });
-    },
-    putIfAbsent(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        assertKey(input.objectRef);
-        const bytes = Buffer.from(input.bytes);
-        try {
-          const output = await putCreateOnly(
-            client,
-            {
-              Bucket,
-              Key: input.objectRef,
-              Body: bytes,
-              ContentLength: bytes.byteLength,
-              ContentType: input.contentType,
-              CacheControl: "no-store",
-              Metadata: { ...input.metadata }
-            },
-            context.signal
-          );
-          return { created: true, nativeVersionRef: versionOf(output) };
-        } catch (error) {
-          if (!isPreconditionFailed(error)) throw error;
-        }
-        const head = await client.send(new HeadObjectCommand({ Bucket, Key: input.objectRef }), {
-          abortSignal: context.signal
-        });
-        return { created: false, nativeVersionRef: versionOf(head) };
-      });
-    },
-    get(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        assertKey(input.objectRef);
-        assertReportingRowReadBounds(input);
-        const selector = selectorOf(input.nativeVersionRef);
-        if (selector === null) return null;
-        const Key = input.objectRef;
-        try {
-          if (input.range?.length === 0) {
-            const head = await client.send(new HeadObjectCommand({ Bucket, Key, ...selector }), {
-              abortSignal: context.signal
-            });
-            if (!servedVersion(head, selector)) return null;
-            if (input.range.offset > Number(head.ContentLength ?? 0)) {
-              throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
-            }
-            return Buffer.alloc(0);
-          }
-          const output = await client.send(
-            new GetObjectCommand({
-              Bucket,
-              Key,
-              ...selector,
-              ...input.range ? { Range: `bytes=${input.range.offset}-${input.range.offset + input.range.length - 1}` } : {}
-            }),
-            { abortSignal: context.signal }
-          );
-          const body = output.Body;
-          if (!body || typeof body[Symbol.asyncIterator] !== "function") {
-            throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object body is not a stream");
-          }
-          if (!servedVersion(output, selector)) {
-            body.destroy?.();
-            return null;
-          }
-          if (typeof output.ContentLength === "number" && output.ContentLength > input.maxBytes) {
-            body.destroy?.();
-            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
-          }
-          return await readReportingRowStream(body, input.maxBytes, context.signal);
-        } catch (error) {
-          if (isNotFound(error) || isPreconditionFailed(error)) return null;
-          if (statusOf(error) === 400 && nameOf(error) !== "InvalidRange") return null;
-          if (isRangeError(error)) {
-            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
-          }
-          throw error;
-        }
-      });
-    },
-    stat(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        assertKey(input.objectRef);
-        const selector = selectorOf(input.nativeVersionRef);
-        if (selector === null) return null;
-        try {
-          const head = await client.send(new HeadObjectCommand({ Bucket, Key: input.objectRef, ...selector }), {
-            abortSignal: context.signal
-          });
-          if (!servedVersion(head, selector)) return null;
-          const size = head.ContentLength;
-          if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
-            throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object metadata is malformed");
-          }
-          return { nativeVersionRef: selector.VersionId, sizeBytes: size };
-        } catch (error) {
-          if (isNotFound(error) || isPreconditionFailed(error)) return null;
-          if (statusOf(error) === 400 || statusOf(error) === 405) return null;
-          throw error;
-        }
-      });
-    },
-    delete(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        assertKey(input.objectRef);
-        const selector = selectorOf(input.nativeVersionRef);
-        if (selector === null) return "absent";
-        const Key = input.objectRef;
-        const signal = context.signal;
-        try {
-          const head = await client.send(new HeadObjectCommand({ Bucket, Key, ...selector }), { abortSignal: signal });
-          if (!servedVersion(head, selector)) return "absent";
-        } catch (error) {
-          if (isNotFound(error) || isPreconditionFailed(error)) return "absent";
-          if (statusOf(error) === 400 || statusOf(error) === 405) return "absent";
-          throw error;
-        }
-        await client.send(new DeleteObjectCommand({ Bucket, Key, VersionId: selector.VersionId }), {
-          abortSignal: signal
-        });
-        return "deleted";
-      });
-    }
-  };
-}
-export {
-  createS3ReportingRowObjectProviderV1
-};

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

@@ -1,148 +0,0 @@
-import type { PostgresReportingLedgerStore } from '../ledger/index.mjs';
-/**
- * Period-aligned retention. Whole periods are retired once
- * `max(statusRetentionDays, recordRetentionDays)` has elapsed since both the
- * period end and its latest publication. `statusRetentionDays` always comes
- * from the service, so retention can never disagree with the commitment the
- * service advertises to buyers.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export interface ReportingRetentionOptionsV1 {
-    enabled: true;
-    recordRetentionDays?: number;
-    limit?: number;
-}
-/**
- * Opt-in compaction of superseded snapshot revisions to metadata only, as
- * adcontextprotocol/adcp#8100 permits. Off unless `enabled: true`. Uses the
- * service's `statusRetentionDays` and `automatedRecoveryWindowSeconds`, so it
- * can never drop content earlier than the commitments advertised to buyers.
- *
- * Compaction takes effect in the AdCP release after November 20, 2026; do not
- * enable it in production before then. See `docs/guides/REPORTING-OPERATIONS.md`.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export interface ReportingCompactionOptionsV1 {
-    enabled: true;
-    /** Revisions compacted per pass. Defaults to 100. */
-    limit?: number;
-}
-/**
- * Change-feed pruning window and the consumer hold shared with retention.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export type ReportingChangeFeedMaintenanceOptionsV1 = boolean | {
-    changeRetentionDays?: number;
-    maxFeedHoldDays?: number;
-};
-/**
- * The ledger-store surface a maintenance pass drives.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export type ReportingLedgerMaintenanceStoreV1 = Pick<PostgresReportingLedgerStore, 'sweepRowWriteIntents' | 'pruneChanges' | 'retireExpiredPeriods'> & Partial<Pick<PostgresReportingLedgerStore, 'compactSupersededSnapshots'>>;
-interface ReportingLedgerMaintenanceTaskOutcomesV1 {
-    'snapshot sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepExpiredState']>>;
-    'row upload sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepRowWriteIntents']>>;
-    'change-feed pruning': Awaited<ReturnType<PostgresReportingLedgerStore['pruneChanges']>>;
-    retention: Awaited<ReturnType<PostgresReportingLedgerStore['retireExpiredPeriods']>>;
-    'snapshot compaction': Awaited<ReturnType<PostgresReportingLedgerStore['compactSupersededSnapshots']>>;
-}
-/**
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export type ReportingLedgerMaintenanceTaskNameV1 = keyof ReportingLedgerMaintenanceTaskOutcomesV1;
-/**
- * A scheduled maintenance pass completed but could not process some items
- * (for example, a retention period whose objects could not be deleted). The
- * pass resumes them next time; repeated reports need operator attention.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export declare class ReportingMaintenancePartialFailureError extends Error {
-    readonly task: string;
-    readonly failedCount: number;
-    readonly failedIds: readonly string[];
-    /**
-     * Backlog the task is not reaching: items backing off, items this host cannot
-     * handle, items that have failed persistently. Appended to the message so
-     * `onError` and the logs carry them.
-     */
-    readonly warnings: readonly string[];
-    constructor(task: string, failedCount: number, failedIds: readonly string[], 
-    /**
-     * Backlog the task is not reaching: items backing off, items this host cannot
-     * handle, items that have failed persistently. Appended to the message so
-     * `onError` and the logs carry them.
-     */
-    warnings?: readonly string[]);
-}
-/**
- * Outcome of one maintenance task. A task that resolved but could not process
- * some items (a retention period whose objects would not delete, an upload that
- * would not sweep) is `completed` with `partialFailure` set; the pass resumes
- * those items next time.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export type ReportingLedgerMaintenanceTaskResultV1 = {
-    [Task in ReportingLedgerMaintenanceTaskNameV1]: {
-        readonly task: Task;
-        readonly status: 'completed';
-        readonly result: ReportingLedgerMaintenanceTaskOutcomesV1[Task];
-        readonly partialFailure?: ReportingMaintenancePartialFailureError;
-    } | {
-        readonly task: Task;
-        readonly status: 'failed';
-        readonly error: unknown;
-    };
-}[ReportingLedgerMaintenanceTaskNameV1];
-/**
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export interface RunReportingLedgerMaintenanceInputV1 {
-    store: ReportingLedgerMaintenanceStoreV1;
-    /**
-     * Expired cursor snapshot and checkpoint sweep. Omitted when the caller has
-     * no way to reach the database, in which case that task is not run.
-     */
-    sweepSnapshots?: (limit: number) => Promise<ReportingLedgerMaintenanceTaskOutcomesV1['snapshot sweep']>;
-    statusRetentionDays: number;
-    /** The service's advertised `automated_recovery_window_seconds`; required when `compaction` is enabled. */
-    automatedRecoveryWindowSeconds?: number | undefined;
-    retention?: ReportingRetentionOptionsV1 | undefined;
-    compaction?: ReportingCompactionOptionsV1 | undefined;
-    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
-    signal?: AbortSignal | undefined;
-    /**
-     * Called, in task order and awaited, for every task that rejected or
-     * partially failed, unless `signal` has aborted (an abort is shutdown, not a
-     * fault).
-     */
-    report?: (error: unknown) => Promise<void>;
-}
-/**
- * The single ledger-maintenance pass shared by the Core service and the
- * production service, so partial-failure surfacing, the `maxFeedHoldDays` that
- * retention honours, per-task limits and abort handling cannot drift between
- * them. Tasks start together, in a fixed order, and are isolated: one task's
- * failure never prevents another from running.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export declare function runReportingLedgerMaintenance(input: RunReportingLedgerMaintenanceInputV1): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
-/**
- * Fail fast on maintenance options the store would otherwise reject on every
- * pass. Mirrors the checks `retireExpiredPeriods` and `pruneChanges` apply.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export declare function assertReportingLedgerMaintenanceOptions(input: {
-    retention?: ReportingRetentionOptionsV1 | undefined;
-    compaction?: ReportingCompactionOptionsV1 | undefined;
-    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
-}, statusRetentionDays: number): void;
-export {};

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

@@ -1,148 +0,0 @@
-import type { PostgresReportingLedgerStore } from '../ledger';
-/**
- * Period-aligned retention. Whole periods are retired once
- * `max(statusRetentionDays, recordRetentionDays)` has elapsed since both the
- * period end and its latest publication. `statusRetentionDays` always comes
- * from the service, so retention can never disagree with the commitment the
- * service advertises to buyers.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export interface ReportingRetentionOptionsV1 {
-    enabled: true;
-    recordRetentionDays?: number;
-    limit?: number;
-}
-/**
- * Opt-in compaction of superseded snapshot revisions to metadata only, as
- * adcontextprotocol/adcp#8100 permits. Off unless `enabled: true`. Uses the
- * service's `statusRetentionDays` and `automatedRecoveryWindowSeconds`, so it
- * can never drop content earlier than the commitments advertised to buyers.
- *
- * Compaction takes effect in the AdCP release after November 20, 2026; do not
- * enable it in production before then. See `docs/guides/REPORTING-OPERATIONS.md`.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export interface ReportingCompactionOptionsV1 {
-    enabled: true;
-    /** Revisions compacted per pass. Defaults to 100. */
-    limit?: number;
-}
-/**
- * Change-feed pruning window and the consumer hold shared with retention.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export type ReportingChangeFeedMaintenanceOptionsV1 = boolean | {
-    changeRetentionDays?: number;
-    maxFeedHoldDays?: number;
-};
-/**
- * The ledger-store surface a maintenance pass drives.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export type ReportingLedgerMaintenanceStoreV1 = Pick<PostgresReportingLedgerStore, 'sweepRowWriteIntents' | 'pruneChanges' | 'retireExpiredPeriods'> & Partial<Pick<PostgresReportingLedgerStore, 'compactSupersededSnapshots'>>;
-interface ReportingLedgerMaintenanceTaskOutcomesV1 {
-    'snapshot sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepExpiredState']>>;
-    'row upload sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepRowWriteIntents']>>;
-    'change-feed pruning': Awaited<ReturnType<PostgresReportingLedgerStore['pruneChanges']>>;
-    retention: Awaited<ReturnType<PostgresReportingLedgerStore['retireExpiredPeriods']>>;
-    'snapshot compaction': Awaited<ReturnType<PostgresReportingLedgerStore['compactSupersededSnapshots']>>;
-}
-/**
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export type ReportingLedgerMaintenanceTaskNameV1 = keyof ReportingLedgerMaintenanceTaskOutcomesV1;
-/**
- * A scheduled maintenance pass completed but could not process some items
- * (for example, a retention period whose objects could not be deleted). The
- * pass resumes them next time; repeated reports need operator attention.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export declare class ReportingMaintenancePartialFailureError extends Error {
-    readonly task: string;
-    readonly failedCount: number;
-    readonly failedIds: readonly string[];
-    /**
-     * Backlog the task is not reaching: items backing off, items this host cannot
-     * handle, items that have failed persistently. Appended to the message so
-     * `onError` and the logs carry them.
-     */
-    readonly warnings: readonly string[];
-    constructor(task: string, failedCount: number, failedIds: readonly string[], 
-    /**
-     * Backlog the task is not reaching: items backing off, items this host cannot
-     * handle, items that have failed persistently. Appended to the message so
-     * `onError` and the logs carry them.
-     */
-    warnings?: readonly string[]);
-}
-/**
- * Outcome of one maintenance task. A task that resolved but could not process
- * some items (a retention period whose objects would not delete, an upload that
- * would not sweep) is `completed` with `partialFailure` set; the pass resumes
- * those items next time.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export type ReportingLedgerMaintenanceTaskResultV1 = {
-    [Task in ReportingLedgerMaintenanceTaskNameV1]: {
-        readonly task: Task;
-        readonly status: 'completed';
-        readonly result: ReportingLedgerMaintenanceTaskOutcomesV1[Task];
-        readonly partialFailure?: ReportingMaintenancePartialFailureError;
-    } | {
-        readonly task: Task;
-        readonly status: 'failed';
-        readonly error: unknown;
-    };
-}[ReportingLedgerMaintenanceTaskNameV1];
-/**
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export interface RunReportingLedgerMaintenanceInputV1 {
-    store: ReportingLedgerMaintenanceStoreV1;
-    /**
-     * Expired cursor snapshot and checkpoint sweep. Omitted when the caller has
-     * no way to reach the database, in which case that task is not run.
-     */
-    sweepSnapshots?: (limit: number) => Promise<ReportingLedgerMaintenanceTaskOutcomesV1['snapshot sweep']>;
-    statusRetentionDays: number;
-    /** The service's advertised `automated_recovery_window_seconds`; required when `compaction` is enabled. */
-    automatedRecoveryWindowSeconds?: number | undefined;
-    retention?: ReportingRetentionOptionsV1 | undefined;
-    compaction?: ReportingCompactionOptionsV1 | undefined;
-    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
-    signal?: AbortSignal | undefined;
-    /**
-     * Called, in task order and awaited, for every task that rejected or
-     * partially failed, unless `signal` has aborted (an abort is shutdown, not a
-     * fault).
-     */
-    report?: (error: unknown) => Promise<void>;
-}
-/**
- * The single ledger-maintenance pass shared by the Core service and the
- * production service, so partial-failure surfacing, the `maxFeedHoldDays` that
- * retention honours, per-task limits and abort handling cannot drift between
- * them. Tasks start together, in a fixed order, and are isolated: one task's
- * failure never prevents another from running.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export declare function runReportingLedgerMaintenance(input: RunReportingLedgerMaintenanceInputV1): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
-/**
- * Fail fast on maintenance options the store would otherwise reject on every
- * pass. Mirrors the checks `retireExpiredPeriods` and `pruneChanges` apply.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export declare function assertReportingLedgerMaintenanceOptions(input: {
-    retention?: ReportingRetentionOptionsV1 | undefined;
-    compaction?: ReportingCompactionOptionsV1 | undefined;
-    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
-}, statusRetentionDays: number): void;
-export {};