@adcp/sdk 15.9.1 → 16.0.0-beta.2

package/dist/lib/reporting/ledger/notification-activity.d.ts

@@ -9,6 +9,9 @@ interface ReportingAccountActivityBaseV1 {
     reporting_obligation_id: string;
     occurredAt: string;
 }
+/**
+ * @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 ReportingLifecycleActivityV1 extends ReportingAccountActivityBaseV1 {
     activityType: 'reporting.lifecycle_changed';
     notificationType?: 'reporting.status_changed';
@@ -28,6 +31,9 @@ export interface ReportingLifecycleActivityV1 extends ReportingAccountActivityBa
         };
     };
 }
+/**
+ * @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 ReportingLedgerChangedActivityV1 extends ReportingAccountActivityBaseV1 {
     activityType: 'reporting.ledger_changed';
     notificationType: 'reporting.ledger_changed';
@@ -38,6 +44,9 @@ export interface ReportingLedgerChangedActivityV1 extends ReportingAccountActivi
     reporting_adjustment_id?: string;
     adjusts_reporting_revision_id?: string;
 }
+/**
+ * @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 ReportingDeliveryReadyActivityV1 extends ReportingAccountActivityBaseV1 {
     activityType: 'reporting.delivery_ready';
     notificationType: 'reporting.delivery_ready';
@@ -50,31 +59,53 @@ export interface ReportingDeliveryReadyActivityV1 extends ReportingAccountActivi
     finality: ReportingLedgerRevisionV1['finality'];
     data_through: string | null;
 }
+/**
+ * @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 ReportingNotificationActivityV1 = ReportingLifecycleActivityV1 | ReportingLedgerChangedActivityV1 | ReportingDeliveryReadyActivityV1;
-/** Backwards-compatible lifecycle activity surface returned by listActivity(). */
+/**
+ * Backwards-compatible lifecycle activity surface returned by listActivity().
+ *
+ * @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 ReportingAccountActivityV1 extends ReportingLifecycleActivityV1 {
 }
+/**
+ * @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 ReportingAccountActivityRecordV1 extends ReportingAccountActivityV1 {
     recordedAt: string;
     notificationProjectedAt?: string;
     /** Set when the claim was bounded out of the pending set without delivering. */
     notificationAbandonedAt?: string;
 }
+/**
+ * @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 ReportingNotificationActivityRecordV1 = ReportingNotificationActivityV1 & {
     recordedAt: string;
     notificationProjectedAt?: string;
     notificationAbandonedAt?: string;
 };
+/**
+ * @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 ReportingAccountActivityPageV1 {
     activities: ReportingAccountActivityRecordV1[];
     hasMore: boolean;
     nextCursor?: string;
 }
+/**
+ * @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 ReportingNotificationActivityPageV1 {
     activities: ReportingNotificationActivityRecordV1[];
     hasMore: boolean;
     nextCursor?: string;
 }
+/**
+ * @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 ReportingNotificationRecoveryMetricsV1 {
     claimed: number;
     matched: number;
@@ -88,18 +119,26 @@ export interface ReportingNotificationRecoveryMetricsV1 {
  * Raised when live delivery authority failed closed for an operational reason
  * rather than a deliberate one. The claim is released and retried; the activity
  * is never projected as delivered.
+ *
+ * @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 ReportingNotificationRetryableSuppressionError extends Error {
     readonly reason: WebhookAttemptSuppressionReason;
     readonly name = "ReportingNotificationRetryableSuppressionError";
     constructor(reason: WebhookAttemptSuppressionReason);
 }
+/**
+ * @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 ReportingNotificationProjectionErrorV1 {
     transitionId: string;
     tenantId: string;
     accountId: string;
     attemptCount: number;
 }
+/**
+ * @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 PostgresReportingNotificationActivityOptions {
     db: ReportingLedgerTransactionV1;
     /**
@@ -181,6 +220,9 @@ export interface PostgresReportingNotificationActivityOptions {
      */
     maxAttempts?: number;
 }
+/**
+ * @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 PostgresReportingNotificationActivityRuntime {
     readonly port: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
     readonly migrations: {
@@ -216,11 +258,21 @@ export interface PostgresReportingNotificationActivityRuntime {
         limit?: number;
     }): Promise<number>;
 }
+/**
+ * @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 getReportingNotificationActivityMigration(options?: {
     tableName?: string;
 }): string;
-/** Child table holding one row per frozen recipient. */
+/**
+ * Child table holding one row per frozen recipient.
+ *
+ * @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 recipientTableName(tableName?: string): string;
+/**
+ * @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 const REPORTING_NOTIFICATION_ACTIVITY_MIGRATION: string;
 /**
  * Builds the durable pre-POST attempt checkpoint for the reporting activity
@@ -237,7 +289,11 @@ export declare const REPORTING_NOTIFICATION_ACTIVITY_MIGRATION: string;
  * lease: a checkpoint only ever makes a recipient less revisable, which is the
  * safe direction, and an outbox worker legitimately holds no activity lease.
  */
-/** Durable store a checkpoint is bound to, so a mismatched pairing cannot be silent. */
+/**
+ * Durable store a checkpoint is bound to, so a mismatched pairing cannot be silent.
+ *
+ * @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 ReportingNotificationAttemptCheckpointV1 {
     (input: Readonly<NotificationDeliveryAttemptCheckpointInput>): Promise<void | number>;
     /**
@@ -252,6 +308,9 @@ export interface ReportingNotificationAttemptCheckpointV1 {
         tableName: string;
     }>;
 }
+/**
+ * @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 createPostgresReportingNotificationAttemptCheckpoint(options: {
     db: ReportingLedgerTransactionV1;
     namespace?: string;
@@ -266,5 +325,8 @@ export declare function createPostgresReportingNotificationAttemptCheckpoint(opt
      */
     eventTypes?: readonly string[];
 }): ReportingNotificationAttemptCheckpointV1;
+/**
+ * @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 createPostgresReportingNotificationActivityRuntime(options: PostgresReportingNotificationActivityOptions): PostgresReportingNotificationActivityRuntime;
 export {};

package/dist/lib/reporting/ledger/object-writes.d.mts

@@ -1,44 +1,85 @@
+/**
+ * @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 ReportingObjectWriteConflictError extends Error {
     constructor();
 }
-/** Symbol branding preserves errors when CJS stores are paired with ESM fences. */
+/**
+ * Symbol branding preserves errors when CJS stores are paired with ESM fences.
+ *
+ * @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 isReportingObjectWriteConflictError(error: unknown): boolean;
+/**
+ * @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 ReportingObjectWriteNotRevokedError extends Error {
     constructor();
 }
+/**
+ * @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 isReportingObjectWriteNotRevokedError(error: unknown): boolean;
-/** Non-secret destination identity, scoped to the store's isolated tenant database. */
+/**
+ * Non-secret destination identity, scoped to the store's isolated tenant database.
+ *
+ * @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 ReportingObjectWriteScopeV1 {
     account_id: string;
     destination_ref: string;
     generation: number;
 }
+/**
+ * @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 ReportingObjectWriteV1 {
     bucket: string;
     object_name: string;
     sha256: string;
     size_bytes: number;
 }
+/**
+ * @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 ReportingObjectWriteBindingV1 {
     bucket: string;
     /** SHA-256 of a host-owned deployment namespace; immutable per authorization generation. */
     namespace_key: string;
 }
+/**
+ * @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 ReportingObjectWriteContextV1 {
     signal?: AbortSignal;
 }
+/**
+ * @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 reportingObjectWriteScopeKey(scope: ReportingObjectWriteScopeV1): string;
+/**
+ * @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 reportingObjectWriteName(scope: ReportingObjectWriteScopeV1, binding: ReportingObjectWriteBindingV1, planId: string, index: number): string;
+/**
+ * @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 ReportingObjectWritePlanV1 extends ReportingObjectWriteScopeV1 {
     provider: ReportingObjectWriteBindingV1;
     /** Stable opaque identity for the same logical delivery across retries. */
     plan_id: string;
     objects: readonly ReportingObjectWriteV1[];
 }
+/**
+ * @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 ReportingObjectWriteCursorV1 {
     plan_id: string;
     object_index: number;
 }
+/**
+ * @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 ReportingObjectWriteStoreV1 {
     /** Registration and destination revocation MUST share one authority/lock boundary. */
     registerObjectWritePlan(plan: ReportingObjectWritePlanV1, context?: ReportingObjectWriteContextV1): Promise<'registered' | 'unchanged' | 'revoked'>;
@@ -54,16 +95,34 @@ export interface ReportingObjectWriteStoreV1 {
         tombstone_generation: string;
     }, context?: ReportingObjectWriteContextV1): Promise<void>;
 }
-/** Apply after REPORTING_MANAGED_DELIVERY_MIGRATION. Additive and independently opt-in. */
+/**
+ * Apply after REPORTING_MANAGED_DELIVERY_MIGRATION. Additive and independently opt-in.
+ *
+ * @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 const REPORTING_OBJECT_WRITE_MIGRATION = "\nCREATE TABLE IF NOT EXISTS adcp_reporting_object_write_bindings (\n  account_id TEXT NOT NULL,\n  destination_ref TEXT NOT NULL,\n  generation BIGINT NOT NULL,\n  bucket TEXT NOT NULL,\n  namespace_key TEXT NOT NULL CHECK (namespace_key ~ '^[a-f0-9]{64}$'),\n  PRIMARY KEY (account_id, destination_ref, generation),\n  FOREIGN KEY (account_id, destination_ref, generation)\n    REFERENCES adcp_reporting_destination_authorizations(account_id, destination_ref, generation)\n);\nCREATE TABLE IF NOT EXISTS adcp_reporting_object_write_plans (\n  account_id TEXT NOT NULL,\n  destination_ref TEXT NOT NULL,\n  generation BIGINT NOT NULL,\n  plan_id TEXT NOT NULL CHECK (plan_id ~ '^[a-f0-9]{64}$'),\n  fingerprint TEXT NOT NULL,\n  PRIMARY KEY (account_id, destination_ref, generation, plan_id),\n  FOREIGN KEY (account_id, destination_ref, generation)\n    REFERENCES adcp_reporting_destination_authorizations(account_id, destination_ref, generation)\n);\nCREATE TABLE IF NOT EXISTS adcp_reporting_object_writes (\n  account_id TEXT NOT NULL,\n  destination_ref TEXT NOT NULL,\n  generation BIGINT NOT NULL,\n  plan_id TEXT NOT NULL,\n  object_index INTEGER NOT NULL CHECK (object_index >= 0 AND object_index < 128),\n  bucket TEXT NOT NULL,\n  object_name TEXT NOT NULL,\n  sha256 TEXT NOT NULL CHECK (sha256 ~ '^[a-f0-9]{64}$'),\n  size_bytes BIGINT NOT NULL CHECK (size_bytes >= 0 AND size_bytes <= 67108864),\n  fenced_at TIMESTAMPTZ,\n  tombstone_generation TEXT,\n  PRIMARY KEY (account_id, destination_ref, generation, plan_id, object_index),\n  UNIQUE (bucket, object_name),\n  FOREIGN KEY (account_id, destination_ref, generation, plan_id)\n    REFERENCES adcp_reporting_object_write_plans(account_id, destination_ref, generation, plan_id)\n);\n";
+/**
+ * @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 assertReportingObjectWriteScope(scope: ReportingObjectWriteScopeV1): void;
+/**
+ * @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 reportingObjectWritePlanFingerprint(plan: ReportingObjectWritePlanV1): string;
-/** Opt-in authority for complete provider adapters; the original primitive store port is unchanged. */
+/**
+ * Opt-in authority for complete provider adapters; the original primitive store port is unchanged.
+ *
+ * @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 ReportingObjectWriteAuthorityStoreV1 extends ReportingObjectWriteStoreV1 {
     probeObjectWriteAuthority(context?: ReportingObjectWriteContextV1): Promise<boolean>;
     getObjectWriteAuthorityId(context?: ReportingObjectWriteContextV1): Promise<string>;
     getAuthorizedObjectWriteBinding(scope: ReportingObjectWriteScopeV1, context?: ReportingObjectWriteContextV1): Promise<ReportingObjectWriteBindingV1 | null>;
     getObjectWritePlan(scope: ReportingObjectWriteScopeV1, planId: string, context?: ReportingObjectWriteContextV1): Promise<ReportingObjectWritePlanV1 | null>;
 }
-/** PostgreSQL 13+; apply after REPORTING_OBJECT_WRITE_MIGRATION. Identity survives replica/worker restart. */
+/**
+ * PostgreSQL 13+; apply after REPORTING_OBJECT_WRITE_MIGRATION. Identity survives replica/worker restart.
+ *
+ * @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 const REPORTING_OBJECT_WRITE_AUTHORITY_MIGRATION = "\nCREATE TABLE IF NOT EXISTS adcp_reporting_object_write_authority (\n  singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),\n  installation_id UUID NOT NULL DEFAULT gen_random_uuid(),\n  schema_version INTEGER NOT NULL DEFAULT 1 CHECK (schema_version = 1)\n);\nINSERT INTO adcp_reporting_object_write_authority (singleton) VALUES (TRUE) ON CONFLICT DO NOTHING;\n";

package/dist/lib/reporting/ledger/object-writes.d.ts

@@ -1,44 +1,85 @@
+/**
+ * @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 ReportingObjectWriteConflictError extends Error {
     constructor();
 }
-/** Symbol branding preserves errors when CJS stores are paired with ESM fences. */
+/**
+ * Symbol branding preserves errors when CJS stores are paired with ESM fences.
+ *
+ * @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 isReportingObjectWriteConflictError(error: unknown): boolean;
+/**
+ * @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 ReportingObjectWriteNotRevokedError extends Error {
     constructor();
 }
+/**
+ * @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 isReportingObjectWriteNotRevokedError(error: unknown): boolean;
-/** Non-secret destination identity, scoped to the store's isolated tenant database. */
+/**
+ * Non-secret destination identity, scoped to the store's isolated tenant database.
+ *
+ * @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 ReportingObjectWriteScopeV1 {
     account_id: string;
     destination_ref: string;
     generation: number;
 }
+/**
+ * @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 ReportingObjectWriteV1 {
     bucket: string;
     object_name: string;
     sha256: string;
     size_bytes: number;
 }
+/**
+ * @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 ReportingObjectWriteBindingV1 {
     bucket: string;
     /** SHA-256 of a host-owned deployment namespace; immutable per authorization generation. */
     namespace_key: string;
 }
+/**
+ * @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 ReportingObjectWriteContextV1 {
     signal?: AbortSignal;
 }
+/**
+ * @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 reportingObjectWriteScopeKey(scope: ReportingObjectWriteScopeV1): string;
+/**
+ * @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 reportingObjectWriteName(scope: ReportingObjectWriteScopeV1, binding: ReportingObjectWriteBindingV1, planId: string, index: number): string;
+/**
+ * @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 ReportingObjectWritePlanV1 extends ReportingObjectWriteScopeV1 {
     provider: ReportingObjectWriteBindingV1;
     /** Stable opaque identity for the same logical delivery across retries. */
     plan_id: string;
     objects: readonly ReportingObjectWriteV1[];
 }
+/**
+ * @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 ReportingObjectWriteCursorV1 {
     plan_id: string;
     object_index: number;
 }
+/**
+ * @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 ReportingObjectWriteStoreV1 {
     /** Registration and destination revocation MUST share one authority/lock boundary. */
     registerObjectWritePlan(plan: ReportingObjectWritePlanV1, context?: ReportingObjectWriteContextV1): Promise<'registered' | 'unchanged' | 'revoked'>;
@@ -54,16 +95,34 @@ export interface ReportingObjectWriteStoreV1 {
         tombstone_generation: string;
     }, context?: ReportingObjectWriteContextV1): Promise<void>;
 }
-/** Apply after REPORTING_MANAGED_DELIVERY_MIGRATION. Additive and independently opt-in. */
+/**
+ * Apply after REPORTING_MANAGED_DELIVERY_MIGRATION. Additive and independently opt-in.
+ *
+ * @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 const REPORTING_OBJECT_WRITE_MIGRATION = "\nCREATE TABLE IF NOT EXISTS adcp_reporting_object_write_bindings (\n  account_id TEXT NOT NULL,\n  destination_ref TEXT NOT NULL,\n  generation BIGINT NOT NULL,\n  bucket TEXT NOT NULL,\n  namespace_key TEXT NOT NULL CHECK (namespace_key ~ '^[a-f0-9]{64}$'),\n  PRIMARY KEY (account_id, destination_ref, generation),\n  FOREIGN KEY (account_id, destination_ref, generation)\n    REFERENCES adcp_reporting_destination_authorizations(account_id, destination_ref, generation)\n);\nCREATE TABLE IF NOT EXISTS adcp_reporting_object_write_plans (\n  account_id TEXT NOT NULL,\n  destination_ref TEXT NOT NULL,\n  generation BIGINT NOT NULL,\n  plan_id TEXT NOT NULL CHECK (plan_id ~ '^[a-f0-9]{64}$'),\n  fingerprint TEXT NOT NULL,\n  PRIMARY KEY (account_id, destination_ref, generation, plan_id),\n  FOREIGN KEY (account_id, destination_ref, generation)\n    REFERENCES adcp_reporting_destination_authorizations(account_id, destination_ref, generation)\n);\nCREATE TABLE IF NOT EXISTS adcp_reporting_object_writes (\n  account_id TEXT NOT NULL,\n  destination_ref TEXT NOT NULL,\n  generation BIGINT NOT NULL,\n  plan_id TEXT NOT NULL,\n  object_index INTEGER NOT NULL CHECK (object_index >= 0 AND object_index < 128),\n  bucket TEXT NOT NULL,\n  object_name TEXT NOT NULL,\n  sha256 TEXT NOT NULL CHECK (sha256 ~ '^[a-f0-9]{64}$'),\n  size_bytes BIGINT NOT NULL CHECK (size_bytes >= 0 AND size_bytes <= 67108864),\n  fenced_at TIMESTAMPTZ,\n  tombstone_generation TEXT,\n  PRIMARY KEY (account_id, destination_ref, generation, plan_id, object_index),\n  UNIQUE (bucket, object_name),\n  FOREIGN KEY (account_id, destination_ref, generation, plan_id)\n    REFERENCES adcp_reporting_object_write_plans(account_id, destination_ref, generation, plan_id)\n);\n";
+/**
+ * @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 assertReportingObjectWriteScope(scope: ReportingObjectWriteScopeV1): void;
+/**
+ * @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 reportingObjectWritePlanFingerprint(plan: ReportingObjectWritePlanV1): string;
-/** Opt-in authority for complete provider adapters; the original primitive store port is unchanged. */
+/**
+ * Opt-in authority for complete provider adapters; the original primitive store port is unchanged.
+ *
+ * @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 ReportingObjectWriteAuthorityStoreV1 extends ReportingObjectWriteStoreV1 {
     probeObjectWriteAuthority(context?: ReportingObjectWriteContextV1): Promise<boolean>;
     getObjectWriteAuthorityId(context?: ReportingObjectWriteContextV1): Promise<string>;
     getAuthorizedObjectWriteBinding(scope: ReportingObjectWriteScopeV1, context?: ReportingObjectWriteContextV1): Promise<ReportingObjectWriteBindingV1 | null>;
     getObjectWritePlan(scope: ReportingObjectWriteScopeV1, planId: string, context?: ReportingObjectWriteContextV1): Promise<ReportingObjectWritePlanV1 | null>;
 }
-/** PostgreSQL 13+; apply after REPORTING_OBJECT_WRITE_MIGRATION. Identity survives replica/worker restart. */
+/**
+ * PostgreSQL 13+; apply after REPORTING_OBJECT_WRITE_MIGRATION. Identity survives replica/worker restart.
+ *
+ * @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 const REPORTING_OBJECT_WRITE_AUTHORITY_MIGRATION = "\nCREATE TABLE IF NOT EXISTS adcp_reporting_object_write_authority (\n  singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),\n  installation_id UUID NOT NULL DEFAULT gen_random_uuid(),\n  schema_version INTEGER NOT NULL DEFAULT 1 CHECK (schema_version = 1)\n);\nINSERT INTO adcp_reporting_object_write_authority (singleton) VALUES (TRUE) ON CONFLICT DO NOTHING;\n";

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

@@ -12,12 +12,22 @@ interface ReportingPgClient {
     query<Row extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<ReportingPgResult<Row>>;
     release(error?: Error): void;
 }
+/**
+ * @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 ReportingPgPool {
     query<Row extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<ReportingPgResult<Row>>;
     connect(): Promise<ReportingPgClient>;
 }
+/**
+ * @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 const REPORTING_LEDGER_MIGRATION: string;
-/** Constraint installed by {@link REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION}. */
+/**
+ * Constraint installed by {@link REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION}.
+ *
+ * @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 const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reporting_transitions_finality_recorded";
 /**
  * Cutover migration that fences pre-SDK-14 writers out of the transition log.
@@ -39,8 +49,13 @@ export declare const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reportin
  * multiply finality-only events, which is the intended trade: loud rejection
  * beats a quietly broken invariant. Idempotent and re-runnable; it takes no lock
  * once installed.
+ *
+ * @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 const REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION: string;
+/**
+ * @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 PostgresReportingLedgerStoreOptions {
     /** Assert that the supplied PostgreSQL database/schema is isolated to this deployment. */
     acknowledgeIsolatedDatabase?: boolean;
@@ -103,21 +118,38 @@ export interface PostgresReportingLedgerStoreOptions {
      */
     changeFeed?: boolean;
 }
+/**
+ * @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 ReportingLedgerLeaseLostError extends Error {
     constructor(message?: string);
 }
-/** A planner or writer named a period whose ledger records were retired by retention. */
+/**
+ * A planner or writer named a period whose ledger records were retired by 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 declare class ReportingLedgerPeriodRetiredError extends Error {
     constructor(message?: string);
 }
+/**
+ * @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 ReportingLedgerContinuityError extends Error {
     constructor(message?: string);
 }
-/** Bounded global cleanup for expired cursor snapshots and changes checkpoints. */
+/**
+ * Bounded global cleanup for expired cursor snapshots and changes checkpoints.
+ *
+ * @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 sweepExpiredReportingLedgerState(pool: Pick<ReportingPgPool, 'query'>, limit?: number): Promise<{
     snapshotsDeleted: number;
     checkpointsDeleted: number;
 }>;
+/**
+ * @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 PostgresReportingLedgerStore implements ReportingLedgerStore {
     private readonly pool;
     /**
@@ -151,9 +183,11 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     /** Append one host change-feed row inside the caller's account-locked transaction. */
     private appendChange;
     /**
-     * Throws `INVALID_INPUT` when any configured object row binding's key template omits
-     * `{revision_key}`, which makes snapshot compaction unsafe (see `compactSupersededSnapshots`).
-     * Called by `compactSupersededSnapshots` and by service construction when compaction is enabled.
+     * Defense in depth for snapshot compaction (see `compactSupersededSnapshots`): throws `INVALID_INPUT`
+     * if a writable object row binding's key template omits `{revision_key}`. Every such binding is
+     * already refused when the store is configured, so this only guards a configuration changed after
+     * construction; `readOnly` bindings are skipped. Called by `compactSupersededSnapshots` and by
+     * service construction when compaction is enabled.
      */
     assertCompactionSafeRowBindings(): void;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */
@@ -475,9 +509,9 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     /**
      * Delete external row objects, skipping any object another row set still references.
      *
-     * A custom `keyTemplate` need only include `{content_sha256}` and `{chunk_index}`, so row sets
-     * from different obligations or accounts with identical chunk content can share one object (a
-     * create-only write adopts an existing object). An object is therefore deleted only when no
+     * Object keys are unique per row set (every writable template includes `{revision_key}`), but header-only
+     * revisions share chunks within an obligation and rows written under an older template can name one
+     * object from several row sets. An object is therefore deleted only when no
      * chunk of a live (or unavailable) row set outside this operation references the same binding,
      * key and native version, and no other open write intent created it. Row sets already `pruning`
      * or `pruned` do not count: their own operation deletes the object, and counting them would let