@adcp/sdk 15.8.1 → 16.0.0-beta.1

package/dist/lib/reporting/ledger/row-storage-object.mjs

@@ -3,6 +3,9 @@ import { promises as fs } from "fs";
 import * as path from "path";
 import { canonicalize } from "../../utils/jcs.mjs";
 import { ReportingRowStoreError } from "./row-storage-errors.mjs";
+import { reportingPeriodDate } from "./schedule.mjs";
+const REPORTING_ROW_OBJECT_REF_MAX_LENGTH = 1024;
+const REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH = 1024;
 const REPORTING_ROW_KEY_PLACEHOLDERS = Object.freeze([
   "prefix",
   "namespace_key",
@@ -17,13 +20,18 @@ const REPORTING_ROW_DEFAULT_KEY_TEMPLATE = "{prefix}/{namespace_key}/{account_ke
 const PREFIX = /^[A-Za-z0-9_.=-]+(?:\/[A-Za-z0-9_.=-]+)*$/;
 const KEY = /^[A-Za-z0-9_.=-]+(?:\/[A-Za-z0-9_.=-]+)*$/;
 const PLACEHOLDER = /\{([a-z0-9_]+)\}/g;
-function assertReportingRowKeyTemplateV1(template) {
+function assertReportingRowKeyTemplateV1(template, options = {}) {
   if (!template.startsWith("{prefix}/{namespace_key}/")) {
     throw new ReportingRowStoreError("INVALID_INPUT", "key templates must begin with {prefix}/{namespace_key}/");
   }
-  for (const required of ["{content_sha256}", "{chunk_index}"]) {
+  const requiredPlaceholders = ["{content_sha256}", "{chunk_index}"];
+  if (options.requireRevisionKey ?? true) requiredPlaceholders.push("{revision_key}");
+  for (const required of requiredPlaceholders) {
     if (!template.includes(required)) {
-      throw new ReportingRowStoreError("INVALID_INPUT", `key templates must include ${required}`);
+      throw new ReportingRowStoreError(
+        "INVALID_INPUT",
+        required === "{revision_key}" ? "key templates must include {revision_key} so every row set has unique object keys. A binding identity includes its template, so add it under a NEW binding ID and keep the old definition configured with `readOnly: true` while rows reference it (rows already written stay readable at their recorded object_ref)" : `key templates must include ${required}`
+      );
     }
   }
   const unknown = [...template.matchAll(PLACEHOLDER)].map((match) => match[1]).filter((name) => !REPORTING_ROW_KEY_PLACEHOLDERS.includes(name));
@@ -51,7 +59,8 @@ function renderReportingRowObjectKeyV1(input) {
     prefix: input.prefix,
     namespace_key: input.namespaceKey,
     account_key: reportingRowAccountKeyV1(input.namespaceKey, input.accountId),
-    period_date: periodDate(input.periodStart),
+    // Rendered only when the template uses it, so a template without {period_date} needs no timezone.
+    period_date: input.template.includes("{period_date}") ? renderedPeriodDate(input.periodStart, input.sourceTimezone) : "",
     finality: input.finality ?? "adjustment",
     revision_key: reportingRowRevisionKeyV1(input.rowSetId),
     content_sha256: input.contentSha256,
@@ -61,13 +70,30 @@ function renderReportingRowObjectKeyV1(input) {
   if (!KEY.test(key) || key.split("/").some((segment) => segment === "." || segment === "..") || !key.startsWith(`${input.prefix}/${input.namespaceKey}/`)) {
     throw new ReportingRowStoreError("INVALID_INPUT", "rendered object key escapes the binding prefix");
   }
+  if (key.length > REPORTING_ROW_OBJECT_REF_MAX_LENGTH) {
+    throw new ReportingRowStoreError(
+      "INVALID_INPUT",
+      `rendered object key exceeds ${REPORTING_ROW_OBJECT_REF_MAX_LENGTH} characters (AdCP object_ref bound)`
+    );
+  }
   return key;
 }
-function periodDate(periodStart) {
+function renderedPeriodDate(periodStart, sourceTimezone) {
   if (!periodStart) return "undated";
-  const parsed = new Date(periodStart);
-  if (Number.isNaN(parsed.getTime())) return "undated";
-  return parsed.toISOString().slice(0, 10).replace(/-/g, "/");
+  if (!sourceTimezone) {
+    throw new ReportingRowStoreError(
+      "INVALID_INPUT",
+      "a period start needs its source_timezone to render {period_date}"
+    );
+  }
+  try {
+    return reportingPeriodDate(periodStart, sourceTimezone);
+  } catch {
+    throw new ReportingRowStoreError(
+      "INVALID_INPUT",
+      "period start or source_timezone is invalid; cannot render {period_date}"
+    );
+  }
 }
 function createFilesystemReportingRowObjectProviderV1(options) {
   const roots = /* @__PURE__ */ new Map();
@@ -104,7 +130,7 @@ function createFilesystemReportingRowObjectProviderV1(options) {
     },
     async putIfAbsent(input, context) {
       context.signal.throwIfAborted();
-      const target = resolve(input.location, input.key);
+      const target = resolve(input.location, input.objectRef);
       await fs.mkdir(path.dirname(target), { recursive: true });
       const temporary = `${target}.${randomUUID()}.tmp`;
       const handle = await fs.open(temporary, "wx");
@@ -118,10 +144,10 @@ function createFilesystemReportingRowObjectProviderV1(options) {
       }
       try {
         await fs.link(temporary, target);
-        return { created: true, nativeVersion: await version(target) };
+        return { created: true, nativeVersionRef: await version(target) };
       } catch (error) {
         if (error.code === "EEXIST") {
-          return { created: false, nativeVersion: await version(target) };
+          return { created: false, nativeVersionRef: await version(target) };
         }
         throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "filesystem write failed");
       } finally {
@@ -130,7 +156,7 @@ function createFilesystemReportingRowObjectProviderV1(options) {
     },
     async get(input, context) {
       context.signal.throwIfAborted();
-      const target = resolve(input.location, input.key);
+      const target = resolve(input.location, input.objectRef);
       let handle;
       try {
         handle = await fs.open(target, "r");
@@ -140,7 +166,7 @@ function createFilesystemReportingRowObjectProviderV1(options) {
       }
       try {
         const stat = await handle.stat({ bigint: true });
-        if (versionOf(stat) !== input.nativeVersion) return null;
+        if (versionOf(stat) !== input.nativeVersionRef) return null;
         const size = Number(stat.size);
         const offset = input.range?.offset ?? 0;
         const length = input.range?.length ?? size - offset;
@@ -157,11 +183,22 @@ function createFilesystemReportingRowObjectProviderV1(options) {
         await handle.close();
       }
     },
+    async stat(input, context) {
+      context.signal.throwIfAborted();
+      const target = resolve(input.location, input.objectRef);
+      try {
+        const stat = await fs.stat(target, { bigint: true });
+        return versionOf(stat) === input.nativeVersionRef ? { nativeVersionRef: input.nativeVersionRef, sizeBytes: Number(stat.size) } : null;
+      } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "filesystem stat failed");
+      }
+    },
     async delete(input, context) {
       context.signal.throwIfAborted();
-      const target = resolve(input.location, input.key);
+      const target = resolve(input.location, input.objectRef);
       try {
-        if (await version(target) !== input.nativeVersion) return "absent";
+        if (await version(target) !== input.nativeVersionRef) return "absent";
         await fs.unlink(target);
         return "deleted";
       } catch (error) {
@@ -183,64 +220,98 @@ async function runReportingRowObjectProviderConformanceV1(provider, input) {
   await provider.probe(input, context);
   passed.push("probe");
   const created = await provider.putIfAbsent(
-    { ...base, key, bytes: first, contentType: "application/x-ndjson", metadata },
+    { ...base, objectRef: key, bytes: first, contentType: "application/x-ndjson", metadata },
     context
   );
-  if (!created.created || !created.nativeVersion) throw new Error("putIfAbsent did not create a new object");
+  if (!created.created || !created.nativeVersionRef) throw new Error("putIfAbsent did not create a new object");
   passed.push("create");
   const conflict = await provider.putIfAbsent(
-    { ...base, key, bytes: Buffer.from('{"c":3}\n'), contentType: "application/x-ndjson", metadata },
+    { ...base, objectRef: key, bytes: Buffer.from('{"c":3}\n'), contentType: "application/x-ndjson", metadata },
     context
   );
-  if (conflict.created || conflict.nativeVersion !== created.nativeVersion) {
+  if (conflict.created || conflict.nativeVersionRef !== created.nativeVersionRef) {
     throw new Error("putIfAbsent replaced or re-versioned an existing object");
   }
-  const stored = await provider.get({ ...base, key, nativeVersion: created.nativeVersion, maxBytes: 1024 }, context);
+  const stored = await provider.get(
+    { ...base, objectRef: key, nativeVersionRef: created.nativeVersionRef, maxBytes: 1024 },
+    context
+  );
   if (!stored || !Buffer.from(stored).equals(first))
     throw new Error("create-only write did not preserve the first bytes");
   passed.push("create-only");
   if (provider.rangedReads) {
     const ranged = await provider.get(
-      { ...base, key, nativeVersion: created.nativeVersion, range: { offset: 8, length: 8 }, maxBytes: 1024 },
+      {
+        ...base,
+        objectRef: key,
+        nativeVersionRef: created.nativeVersionRef,
+        range: { offset: 8, length: 8 },
+        maxBytes: 1024
+      },
       context
     );
     if (!ranged || Buffer.from(ranged).toString("utf8") !== '{"b":2}\n')
       throw new Error("ranged read returned wrong bytes");
     passed.push("ranged-read");
   }
-  if (await provider.get({ ...base, key, nativeVersion: "not-a-version", maxBytes: 1024 }, context) !== null) {
+  if (await provider.get({ ...base, objectRef: key, nativeVersionRef: "not-a-version", maxBytes: 1024 }, context) !== null) {
     throw new Error("get returned bytes for a version that does not exist");
   }
   passed.push("version-pinned-read");
-  if (await provider.delete({ ...base, key, nativeVersion: "not-a-version" }, context) !== "absent") {
+  if (provider.stat) {
+    const stat = await provider.stat({ ...base, objectRef: key, nativeVersionRef: created.nativeVersionRef }, context);
+    if (!stat || stat.sizeBytes !== first.byteLength) throw new Error("stat did not report the stored object size");
+    if (stat.nativeVersionRef !== created.nativeVersionRef) throw new Error("stat did not echo the version it checked");
+    if (await provider.stat({ ...base, objectRef: key, nativeVersionRef: "not-a-version" }, context) !== null) {
+      throw new Error("stat returned metadata for a version that does not exist");
+    }
+    passed.push("version-pinned-stat");
+  }
+  if (await provider.delete({ ...base, objectRef: key, nativeVersionRef: "not-a-version" }, context) !== "absent") {
     throw new Error("delete removed an object at a different version");
   }
-  if (await provider.delete({ ...base, key, nativeVersion: created.nativeVersion }, context) !== "deleted") {
+  if (await provider.delete({ ...base, objectRef: key, nativeVersionRef: created.nativeVersionRef }, context) !== "deleted") {
     throw new Error("delete did not remove the exact version");
   }
-  if (await provider.delete({ ...base, key, nativeVersion: created.nativeVersion }, context) !== "absent") {
+  if (await provider.delete({ ...base, objectRef: key, nativeVersionRef: created.nativeVersionRef }, context) !== "absent") {
     throw new Error("repeated delete was not idempotent");
   }
   passed.push("exact-version-delete");
+  if (provider.stat && await provider.stat({ ...base, objectRef: key, nativeVersionRef: created.nativeVersionRef }, context) !== null) {
+    throw new Error("stat returned metadata for a deleted version");
+  }
   const recreated = await provider.putIfAbsent(
-    { ...base, key, bytes: first, contentType: "application/x-ndjson", metadata },
+    { ...base, objectRef: key, bytes: first, contentType: "application/x-ndjson", metadata },
     context
   );
-  if (!recreated.created || !recreated.nativeVersion) throw new Error("putIfAbsent did not re-create a deleted object");
-  if (recreated.nativeVersion === created.nativeVersion) {
+  if (!recreated.created || !recreated.nativeVersionRef)
+    throw new Error("putIfAbsent did not re-create a deleted object");
+  if (recreated.nativeVersionRef === created.nativeVersionRef) {
     throw new Error("re-creating identical bytes produced the same native version; versions must be write-unique");
   }
-  if (await provider.delete({ ...base, key, nativeVersion: created.nativeVersion }, context) !== "absent") {
+  if (await provider.delete({ ...base, objectRef: key, nativeVersionRef: created.nativeVersionRef }, context) !== "absent") {
     throw new Error("delete of a stale version removed or reported a later write");
   }
+  if (provider.stat) {
+    if (await provider.stat({ ...base, objectRef: key, nativeVersionRef: created.nativeVersionRef }, context) !== null) {
+      throw new Error("stat of a stale version reported a later write at the same key");
+    }
+    const current = await provider.stat(
+      { ...base, objectRef: key, nativeVersionRef: recreated.nativeVersionRef },
+      context
+    );
+    if (!current || current.sizeBytes !== first.byteLength || current.nativeVersionRef !== recreated.nativeVersionRef) {
+      throw new Error("stat did not report the re-created object");
+    }
+  }
   const survivor = await provider.get(
-    { ...base, key, nativeVersion: recreated.nativeVersion, maxBytes: 1024 },
+    { ...base, objectRef: key, nativeVersionRef: recreated.nativeVersionRef, maxBytes: 1024 },
     context
   );
   if (!survivor || !Buffer.from(survivor).equals(first)) {
     throw new Error("delete of a stale version removed a later write with identical bytes");
   }
-  if (await provider.delete({ ...base, key, nativeVersion: recreated.nativeVersion }, context) !== "deleted") {
+  if (await provider.delete({ ...base, objectRef: key, nativeVersionRef: recreated.nativeVersionRef }, context) !== "deleted") {
     throw new Error("delete did not remove the re-created version");
   }
   passed.push("write-unique-version");
@@ -252,6 +323,8 @@ function sha256Hex(value) {
 export {
   REPORTING_ROW_DEFAULT_KEY_TEMPLATE,
   REPORTING_ROW_KEY_PLACEHOLDERS,
+  REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH,
+  REPORTING_ROW_OBJECT_REF_MAX_LENGTH,
   assertReportingRowKeyTemplateV1,
   assertReportingRowPrefixV1,
   createFilesystemReportingRowObjectProviderV1,

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

@@ -9,7 +9,11 @@ import { type ReportingRowObjectProviderV1 } from './row-storage-object.mjs';
  */
 export { ReportingRowStoreError, isReportingRowStoreError } from './row-storage-errors.mjs';
 export type { ReportingRowStoreErrorCode } from './row-storage-errors.mjs';
-/** 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,18 +203,25 @@ 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
      * depth for compaction, the one path that deletes content while the obligation stays live.
      */
     assertCompactionSafeKeyTemplates(): void;
+    /** IDs of the object bindings this host configures, the only ones it can delete objects through. */
+    objectBindingIds(): string[];
     /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
     ready(): Promise<void>;
     /** Encode rows, prove the chunks reproduce the committed binding, select a binding and plan objects. */
@@ -176,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:
@@ -208,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
@@ -243,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;