@adcp/sdk 15.9.0 → 16.0.0-beta.1

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

@@ -7,26 +7,51 @@
  * binding, and every byte a provider returns is verified against digests
  * committed in PostgreSQL before rows are released.
  */
+/**
+ * @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 ReportingRowObjectContextV1 {
     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 interface ReportingRowObjectLocationV1 {
     /** Non-secret provider coordinates (bucket, container, filesystem root name, endpoint host). */
     readonly location: Readonly<Record<string, string>>;
     /** Host-mapped client reference; never a secret. */
     readonly credentialRef?: string;
 }
+/**
+ * Bounds AdCP puts on `object_ref` and `native_version_ref`
+ * (`reporting-file-object-ref.json`, `reporting-native-version-ref.json`):
+ * 1 to 1024 characters. The row-storage `CHECK` constraints enforce the same.
+ *
+ * @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_ROW_OBJECT_REF_MAX_LENGTH = 1024;
+/**
+ * @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_ROW_NATIVE_VERSION_REF_MAX_LENGTH = 1024;
+/**
+ * @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 ReportingRowObjectPutInputV1 extends ReportingRowObjectLocationV1 {
-    key: string;
+    /** AdCP `object_ref`: decoded, destination-relative object key. */
+    objectRef: string;
     bytes: Uint8Array;
     contentType: 'application/x-ndjson' | 'application/gzip';
     /** Non-secret object metadata (installation and intent identifiers). */
     metadata: Readonly<Record<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 interface ReportingRowObjectGetInputV1 extends ReportingRowObjectLocationV1 {
-    key: string;
-    /** Exact native version recorded at write time. */
-    nativeVersion: string;
+    objectRef: string;
+    /** AdCP `native_version_ref`: the exact native version recorded at write time. */
+    nativeVersionRef: string;
     /** Byte range within the stored object; omit for the whole object. */
     range?: {
         offset: number;
@@ -35,10 +60,23 @@ export interface ReportingRowObjectGetInputV1 extends ReportingRowObjectLocation
     /** Hard cap on bytes read; providers abort beyond it. */
     maxBytes: 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 ReportingRowObjectDeleteInputV1 extends ReportingRowObjectLocationV1 {
-    key: string;
-    nativeVersion: string;
+    objectRef: string;
+    nativeVersionRef: 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 ReportingRowObjectStatInputV1 extends ReportingRowObjectLocationV1 {
+    objectRef: string;
+    nativeVersionRef: 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 ReportingRowObjectProviderV1 {
     /** Registry name, e.g. `filesystem`, `gcs`, `s3`, `azure_blob`. */
     readonly name: string;
@@ -60,35 +98,84 @@ export interface ReportingRowObjectProviderV1 {
      */
     putIfAbsent(input: ReportingRowObjectPutInputV1, context: ReportingRowObjectContextV1): Promise<{
         created: boolean;
-        nativeVersion: string;
+        nativeVersionRef: string;
     }>;
     /** Bytes at the exact native version, or `null` when that version is absent. */
     get(input: ReportingRowObjectGetInputV1, context: ReportingRowObjectContextV1): Promise<Uint8Array | null>;
+    /**
+     * Metadata of the exact native version without reading its bytes: the version it resolved (which must equal the
+     * requested `nativeVersionRef`) and its stored size (`size_bytes`), or `null` when that version is absent. Optional. The commit transaction uses it to
+     * prove an adopted object is unchanged (native versions are write-unique, so the same version at
+     * the recorded size is the same bytes) without downloading it under the account lock. A provider
+     * without `stat` falls back to a full read there. Never return a size for a different version.
+     */
+    stat?(input: ReportingRowObjectStatInputV1, context: ReportingRowObjectContextV1): Promise<{
+        nativeVersionRef: string;
+        sizeBytes: number;
+    } | null>;
     /** Delete the exact native version. Idempotent: `absent` is success. */
     delete(input: ReportingRowObjectDeleteInputV1, context: ReportingRowObjectContextV1): Promise<'deleted' | 'absent'>;
 }
-/** Placeholders allowed in object key templates. */
+/**
+ * Placeholders allowed in object key templates. `{period_date}` renders AdCP's `YYYY-MM-DD`: the calendar
+ * date of the period start in the period's `source_timezone` (never UTC, unless that is the source
+ * timezone). It is one path segment, so the default layout is
+ * `.../{account_key}/2026-10-02/{finality}/...`.
+ *
+ * @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_ROW_KEY_PLACEHOLDERS: readonly ["prefix", "namespace_key", "account_key", "period_date", "finality", "revision_key", "content_sha256", "chunk_index"];
+/**
+ * @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_ROW_DEFAULT_KEY_TEMPLATE = "{prefix}/{namespace_key}/{account_key}/{period_date}/{finality}/{revision_key}/{content_sha256}/{chunk_index}";
-/** Validate an object key template; throws `INVALID_INPUT`. */
-export declare function assertReportingRowKeyTemplateV1(template: string): void;
+/**
+ * Validate an object key template; throws `INVALID_INPUT`. Every template that writes must include
+ * `{revision_key}`, so no two row sets can ever name the same object key; `requireRevisionKey: false`
+ * is for a read-only binding that only reads rows written under an older template.
+ *
+ * @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 assertReportingRowKeyTemplateV1(template: string, options?: {
+    requireRevisionKey?: boolean;
+}): 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 assertReportingRowPrefixV1(prefix: string): void;
-/** Pseudonymous account segment; never a raw account ID. */
+/**
+ * Pseudonymous account segment; never a raw account ID.
+ *
+ * @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 reportingRowAccountKeyV1(namespaceKey: string, accountId: 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 function reportingRowRevisionKeyV1(rowSetId: string): string;
-/** Render one chunk's object key and confine it to the binding's owned prefix. */
+/**
+ * Render one chunk's object key and confine it to the binding's owned prefix.
+ *
+ * @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 renderReportingRowObjectKeyV1(input: {
     template: string;
     prefix: string;
     namespaceKey: string;
     accountId: string;
     rowSetId: string;
+    /** Period start instant; with `sourceTimezone`, renders `{period_date}`. Absent renders `undated`. */
     periodStart?: string;
+    /** The period's `source_timezone`; required whenever `periodStart` is set. Invalid values fail closed. */
+    sourceTimezone?: string;
     finality?: 'snapshot' | 'official';
     contentSha256: string;
     chunkIndex: number;
     compression: 'none' | 'gzip';
 }): 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 FilesystemReportingRowObjectProviderOptionsV1 {
     /**
      * Root name → absolute directory. Bindings name a root (`location.root`);
@@ -100,12 +187,16 @@ export interface FilesystemReportingRowObjectProviderOptionsV1 {
  * Local filesystem provider for tests and single-host deployments. Create-only
  * writes use a temporary file, `fsync`, and `link()` to the final name, which
  * fails rather than replacing an existing object.
+ *
+ * @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 createFilesystemReportingRowObjectProviderV1(options: FilesystemReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;
 /**
  * Behavioural conformance for a custom object provider. Writes and deletes
  * only under `prefix`; run it against a dedicated test bucket or prefix.
  * Resolves with the checks that passed; rejects on the first violation.
+ *
+ * @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 runReportingRowObjectProviderConformanceV1(provider: ReportingRowObjectProviderV1, input: ReportingRowObjectLocationV1 & {
     prefix: string;

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

@@ -30,6 +30,8 @@ var row_storage_object_exports = {};
 __export(row_storage_object_exports, {
   REPORTING_ROW_DEFAULT_KEY_TEMPLATE: () => REPORTING_ROW_DEFAULT_KEY_TEMPLATE,
   REPORTING_ROW_KEY_PLACEHOLDERS: () => REPORTING_ROW_KEY_PLACEHOLDERS,
+  REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH: () => REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH,
+  REPORTING_ROW_OBJECT_REF_MAX_LENGTH: () => REPORTING_ROW_OBJECT_REF_MAX_LENGTH,
   assertReportingRowKeyTemplateV1: () => assertReportingRowKeyTemplateV1,
   assertReportingRowPrefixV1: () => assertReportingRowPrefixV1,
   createFilesystemReportingRowObjectProviderV1: () => createFilesystemReportingRowObjectProviderV1,
@@ -44,6 +46,9 @@ var import_fs = require("fs");
 var path = __toESM(require("path"));
 var import_jcs = require('../../utils/jcs.js');
 var import_row_storage_errors = require('./row-storage-errors.js');
+var import_schedule = require('./schedule.js');
+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",
@@ -58,13 +63,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 import_row_storage_errors.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 import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", `key templates must include ${required}`);
+      throw new import_row_storage_errors.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));
@@ -92,7 +102,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,
@@ -102,13 +113,30 @@ function renderReportingRowObjectKeyV1(input) {
   if (!KEY.test(key) || key.split("/").some((segment) => segment === "." || segment === "..") || !key.startsWith(`${input.prefix}/${input.namespaceKey}/`)) {
     throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "rendered object key escapes the binding prefix");
   }
+  if (key.length > REPORTING_ROW_OBJECT_REF_MAX_LENGTH) {
+    throw new import_row_storage_errors.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 import_row_storage_errors.ReportingRowStoreError(
+      "INVALID_INPUT",
+      "a period start needs its source_timezone to render {period_date}"
+    );
+  }
+  try {
+    return (0, import_schedule.reportingPeriodDate)(periodStart, sourceTimezone);
+  } catch {
+    throw new import_row_storage_errors.ReportingRowStoreError(
+      "INVALID_INPUT",
+      "period start or source_timezone is invalid; cannot render {period_date}"
+    );
+  }
 }
 function createFilesystemReportingRowObjectProviderV1(options) {
   const roots = /* @__PURE__ */ new Map();
@@ -145,7 +173,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 import_fs.promises.mkdir(path.dirname(target), { recursive: true });
       const temporary = `${target}.${(0, import_crypto.randomUUID)()}.tmp`;
       const handle = await import_fs.promises.open(temporary, "wx");
@@ -159,10 +187,10 @@ function createFilesystemReportingRowObjectProviderV1(options) {
       }
       try {
         await import_fs.promises.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 import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "filesystem write failed");
       } finally {
@@ -171,7 +199,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 import_fs.promises.open(target, "r");
@@ -181,7 +209,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;
@@ -198,11 +226,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 import_fs.promises.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 import_row_storage_errors.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 import_fs.promises.unlink(target);
         return "deleted";
       } catch (error) {
@@ -224,64 +263,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");
@@ -294,6 +367,8 @@ function sha256Hex(value) {
 0 && (module.exports = {
   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,