@adcp/sdk 15.9.1 → 16.0.0-beta.2

package/dist/lib/reporting/ledger/row-storage.d.ts

@@ -9,7 +9,11 @@ import { type ReportingRowObjectProviderV1 } from './row-storage-object';
  */
 export { ReportingRowStoreError, isReportingRowStoreError } from './row-storage-errors';
 export type { ReportingRowStoreErrorCode } from './row-storage-errors';
-/** Rows stored as chunk bodies in the ledger's own PostgreSQL schema. */
+/**
+ * Rows stored as chunk bodies in the ledger's own PostgreSQL schema.
+ *
+ * @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 ReportingPostgresRowBindingV1 {
     kind: 'postgres';
 }
@@ -18,6 +22,8 @@ export interface ReportingPostgresRowBindingV1 {
  * definition lives in host code, which makes it the allowlist: a row set
  * whose recorded binding identity differs from the configured definition is
  * never read from or written to.
+ *
+ * @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 ReportingObjectRowBindingV1 {
     kind: 'object';
@@ -27,22 +33,41 @@ export interface ReportingObjectRowBindingV1 {
     location: Readonly<Record<string, string>>;
     /** Owned key prefix. Sweeps and deletes never touch keys outside it. */
     prefix: string;
-    /** Object key template; see `REPORTING_ROW_DEFAULT_KEY_TEMPLATE`. */
+    /**
+     * Object key template; see `REPORTING_ROW_DEFAULT_KEY_TEMPLATE`. It must include `{revision_key}`, so every
+     * row set writes its own object keys (a read-only binding is exempt).
+     */
     keyTemplate?: string;
+    /**
+     * Keep this binding configured only to read (and retire) row sets already written through it, for
+     * example under an older template without `{revision_key}`. A read-only binding is never selected for
+     * new writes and is exempt from the `{revision_key}` requirement; reads use each chunk's recorded
+     * `object_ref`, never a re-rendered key. Not part of the binding's identity.
+     */
+    readOnly?: boolean;
     /** Stored encoding; digests always cover uncompressed bytes. Default `gzip`. */
     compression?: 'none' | 'gzip';
     /** Host-mapped client reference passed to the provider; never a secret. */
     credentialRef?: 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 ReportingRowBindingDefinitionV1 = ReportingPostgresRowBindingV1 | ReportingObjectRowBindingV1;
+/**
+ * @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 ReportingRowBindingSelectionInputV1 {
     account_id: string;
     reporting_obligation_id: string;
     row_set_kind: 'revision' | 'adjustment';
     finality?: 'snapshot' | 'official';
     row_count: number;
-    canonical_byte_count: number;
+    content_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 ReportingRowStorageOptionsV1 {
     /**
      * Logical binding ID → immutable definition. Defaults to a single
@@ -64,6 +89,9 @@ export interface ReportingRowStorageOptionsV1 {
     /** Deadline for one object read. Default 30 seconds. */
     readDeadlineMilliseconds?: 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 ReportingRowSetPrepareInputV1 {
     rowSetId: string;
     rowSetKind: 'revision' | 'adjustment';
@@ -71,8 +99,10 @@ export interface ReportingRowSetPrepareInputV1 {
     obligationId: string;
     rows: readonly Record<string, unknown>[];
     finality?: 'snapshot' | 'official';
-    /** Reporting period start, used for `{period_date}` in object keys. */
+    /** Reporting period start, used with `sourceTimezone` for `{period_date}` in object keys. */
     periodStart?: string;
+    /** The period's `source_timezone` (required with `periodStart`): `{period_date}` is the local calendar date. */
+    sourceTimezone?: string;
     /** Committed protocol binding the chunks must reproduce. */
     binding: {
         sha256: string;
@@ -85,11 +115,14 @@ export interface ReportingRowSetPrepareInputV1 {
     bindingId?: string;
 }
 interface PreparedObjectV1 {
-    readonly key: string;
+    readonly objectRef: string;
     readonly physicalBytes: Buffer;
     readonly physicalSha256: string;
     readonly compression: 'none' | 'gzip';
 }
+/**
+ * @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 ReportingPreparedRowSetV1 {
     readonly input: ReportingRowSetPrepareInputV1;
     readonly encoded: ReportingEncodedRowsV1;
@@ -99,13 +132,21 @@ export interface ReportingPreparedRowSetV1 {
     /** Object kind only: one planned object per chunk. */
     readonly objects?: readonly PreparedObjectV1[];
 }
-/** Where one chunk was stored; recorded in the chunk manifest. */
+/**
+ * Where one chunk was stored; recorded in the chunk manifest.
+ *
+ * @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 ReportingRowChunkLocatorV1 {
-    objectKey: string;
-    nativeVersion: string;
+    /** AdCP `object_ref`: decoded, destination-relative, 1 to 1024 characters. */
+    objectRef: string;
+    /** AdCP `native_version_ref`: decoded provider-native immutable version, 1 to 1024 characters. */
+    nativeVersionRef: string;
     compression: 'none' | 'gzip';
+    /** SHA-256 of the stored (possibly compressed) object bytes. */
     physicalSha256: string;
-    physicalByteCount: number;
+    /** AdCP `size_bytes`: the stored object's size, after any compression. */
+    sizeBytes: number;
     /** Whether this upload created the object (as opposed to adopting identical bytes). */
     created: boolean;
 }
@@ -115,7 +156,11 @@ interface QueryableV1 {
         rowCount?: number | null;
     }>;
 }
-/** A row set whose chunk manifest has been verified against its committed digest. */
+/**
+ * A row set whose chunk manifest has been verified against its committed digest.
+ *
+ * @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 ReportingRowSetHandleV1 {
     readonly rowSetId: string;
     readonly rowSetKind: 'revision' | 'adjustment';
@@ -123,7 +168,11 @@ export interface ReportingRowSetHandleV1 {
     readonly obligationId: string;
     readonly digestProfile: 'revision_envelope_v1' | 'rows_v1';
     readonly contentSha256: string;
-    readonly canonicalByteCount: number;
+    /**
+     * Byte count of the content `contentSha256` covers (the committed binding's `byteCount`): for a revision it includes
+     * the envelope, so it is not the sum of the chunks' `canonical_size_bytes`.
+     */
+    readonly contentSizeBytes: number;
     readonly rowCount: number;
     readonly rowManifestSha256: string;
     readonly bindingId: string;
@@ -138,6 +187,8 @@ export interface ReportingRowSetHandleV1 {
  * available once the row-storage migration is applied; object-kind reads need
  * the binding and its provider configured. Writes require an explicit opt-in
  * on the owning store.
+ *
+ * @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 ReportingRowStorageV1 {
     private readonly pool;
@@ -152,12 +203,17 @@ export declare class ReportingRowStorageV1 {
     constructor(pool: QueryableV1, options?: ReportingRowStorageOptionsV1);
     /** Deadline budget a writer must still hold on its lease before uploading. */
     get writeDeadlineMilliseconds(): number;
+    /** Every writable object binding's key template must include `{revision_key}`; throws `INVALID_INPUT`. */
+    private assertBindingKeyTemplates;
     /**
      * Refuse a configuration in which compaction could delete an object a concurrent commit is
      * adopting. An object binding whose key template omits `{revision_key}` can map two revisions
      * with identical chunk content to one object key, and a create-only write adopts an existing
      * object with identical bytes. Compaction deleting that object at the same moment would leave
-     * the newer revision without its rows. The default template includes `{revision_key}`.
+     * the newer revision without its rows. Every writable binding is already required to include
+     * `{revision_key}`, so this cannot fail for a validated configuration. A `readOnly` binding is
+     * skipped: it never takes commits, so nothing can adopt through it, and every delete is
+     * reference-checked.
      *
      * Since the reference-checked, per-object-locked delete this is no longer the only guard: every
      * delete path now skips an object another row set still references. It is kept as defense in
@@ -178,8 +234,8 @@ export declare class ReportingRowStorageV1 {
      * write intent.
      */
     upload(prepared: ReportingPreparedRowSetV1, intentId: string, onCreated: (object: {
-        objectKey: string;
-        nativeVersion: string;
+        objectRef: string;
+        nativeVersionRef: string;
     }) => Promise<void>, signal?: AbortSignal): Promise<ReportingRowChunkLocatorV1[]>;
     /**
      * Persist a prepared row set inside the caller's ledger transaction:
@@ -210,19 +266,26 @@ export declare class ReportingRowStorageV1 {
      * `absent` counts as success. Only object-kind bindings are accepted.
      */
     deleteObjects(bindingId: string, objects: readonly {
-        objectKey: string;
-        nativeVersion: string;
+        objectRef: string;
+        nativeVersionRef: string;
     }[], signal?: AbortSignal): Promise<void>;
     /**
-     * Prove each object is still present at its recorded version with the recorded bytes.
+     * Prove each object is still present at its recorded version with the recorded size.
      * A commit that adopted an object another row set created calls this under the object's
      * lock, so a concurrent delete either finished first (this throws, the commit fails and
      * the writer re-uploads) or sees the commit's chunk reference and skips the delete.
+     *
+     * Native versions are write-unique (S3 VersionId, Azure versionId, GCS generation, filesystem
+     * `ino:birthtime:mtime:size`), so a version-pinned metadata check, "this exact version exists at the
+     * recorded size", proves the object unchanged without downloading it while the commit holds its
+     * locks. Bytes were verified when the object was uploaded or adopted. A custom provider without
+     * `stat` falls back to reading the whole object and comparing its physical digest.
      */
     assertObjectsPresent(bindingId: string, objects: readonly {
-        objectKey: string;
-        nativeVersion: string;
+        objectRef: string;
+        nativeVersionRef: string;
         physicalSha256: string;
+        sizeBytes: number;
     }[], signal?: AbortSignal): Promise<void>;
     /**
      * A live row set in the same obligation and binding whose rows are
@@ -245,5 +308,9 @@ export declare class ReportingRowStorageV1 {
     private provider;
     private register;
 }
-/** Fresh opaque intent identifier for one upload attempt. */
+/**
+ * Fresh opaque intent identifier for one upload attempt.
+ *
+ * @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 reportingRowWriteIntentIdV1(): string;