@adcp/sdk 15.9.0 → 16.0.0-beta.1

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

@@ -24,6 +24,53 @@ __export(row_storage_migration_exports, {
 });
 module.exports = __toCommonJS(row_storage_migration_exports);
 const REPORTING_ROW_STORAGE_MIGRATION = `
+-- Serialize concurrent appliers (several instances may run migrations at startup) so the guarded
+-- renames below cannot race each other. Released at the end of this implicit transaction.
+SELECT pg_advisory_xact_lock(hashtextextended('adcp-reporting-row-storage-migration', 0));
+
+-- In-place upgrade from the pre-AdCP-alignment column names. Every step is guarded, so a fresh
+-- install (no tables yet) and a reapplied migration are both no-ops here.
+DO $align$
+DECLARE
+  renames TEXT[][] := ARRAY[
+    ARRAY['adcp_reporting_row_chunks', 'object_key', 'object_ref'],
+    ARRAY['adcp_reporting_row_chunks', 'native_version', 'native_version_ref'],
+    ARRAY['adcp_reporting_row_chunks', 'byte_count', 'canonical_size_bytes'],
+    ARRAY['adcp_reporting_row_chunks', 'physical_byte_count', 'size_bytes'],
+    ARRAY['adcp_reporting_row_sets', 'canonical_byte_count', 'content_size_bytes']
+  ];
+  item TEXT[];
+BEGIN
+  FOREACH item SLICE 1 IN ARRAY renames LOOP
+    IF EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = current_schema() AND table_name = item[1] AND column_name = item[2]
+    ) AND NOT EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = current_schema() AND table_name = item[1] AND column_name = item[3]
+    ) THEN
+      EXECUTE format('ALTER TABLE %I RENAME COLUMN %I TO %I', item[1], item[2], item[3]);
+    END IF;
+  END LOOP;
+  -- encoding = 'adcp_canonical_jsonl_v1' becomes AdCP's format = 'jsonl' plus
+  -- algorithm = 'adcp_jcs_rows_v1'. The old CHECK admitted one value, so the defaults backfill
+  -- every row without an UPDATE (the immutability trigger forbids one).
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_schema = current_schema() AND table_name = 'adcp_reporting_row_sets' AND column_name = 'encoding'
+  ) AND NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_schema = current_schema() AND table_name = 'adcp_reporting_row_sets' AND column_name = 'format'
+  ) THEN
+    ALTER TABLE adcp_reporting_row_sets
+      ADD COLUMN format TEXT NOT NULL DEFAULT 'jsonl' CHECK (format = 'jsonl'),
+      ADD COLUMN algorithm TEXT NOT NULL DEFAULT 'adcp_jcs_rows_v1' CHECK (algorithm = 'adcp_jcs_rows_v1');
+    ALTER TABLE adcp_reporting_row_sets ALTER COLUMN format DROP DEFAULT, ALTER COLUMN algorithm DROP DEFAULT;
+    ALTER TABLE adcp_reporting_row_sets DROP COLUMN encoding;
+  END IF;
+END
+$align$;
+
 CREATE TABLE IF NOT EXISTS adcp_persistence_installation (
   singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),
   installation_id UUID NOT NULL DEFAULT gen_random_uuid(),
@@ -50,10 +97,11 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_row_sets (
   row_set_kind TEXT NOT NULL CHECK (row_set_kind IN ('revision', 'adjustment')),
   account_id TEXT COLLATE "C" NOT NULL,
   obligation_id TEXT COLLATE "C" NOT NULL REFERENCES adcp_reporting_obligations(obligation_id),
-  encoding TEXT NOT NULL CHECK (encoding = 'adcp_canonical_jsonl_v1'),
+  format TEXT NOT NULL CHECK (format = 'jsonl'),
+  algorithm TEXT NOT NULL CHECK (algorithm = 'adcp_jcs_rows_v1'),
   digest_profile TEXT NOT NULL CHECK (digest_profile IN ('revision_envelope_v1', 'rows_v1')),
   content_sha256 TEXT COLLATE "C" NOT NULL CHECK (content_sha256 ~ '^[0-9a-f]{64}$'),
-  canonical_byte_count BIGINT NOT NULL CHECK (canonical_byte_count > 0),
+  content_size_bytes BIGINT NOT NULL CHECK (content_size_bytes > 0),
   row_count BIGINT NOT NULL CHECK (row_count >= 0),
   row_manifest_sha256 TEXT COLLATE "C" NOT NULL CHECK (row_manifest_sha256 ~ '^[0-9a-f]{64}$'),
   chunk_count INTEGER NOT NULL CHECK (chunk_count >= 0),
@@ -87,27 +135,29 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_row_chunks (
   obligation_id TEXT COLLATE "C" NOT NULL,
   first_ordinal BIGINT NOT NULL CHECK (first_ordinal >= 0),
   row_count INTEGER NOT NULL CHECK (row_count > 0),
-  byte_count BIGINT NOT NULL CHECK (byte_count > 0),
+  canonical_size_bytes BIGINT NOT NULL CHECK (canonical_size_bytes > 0),
   sha256 TEXT COLLATE "C" NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'),
   segments JSONB NOT NULL CHECK (jsonb_typeof(segments) = 'array'),
-  object_key TEXT COLLATE "C",
-  native_version TEXT,
+  object_ref TEXT COLLATE "C" CONSTRAINT adcp_reporting_row_chunks_object_ref_bounds
+    CHECK (object_ref IS NULL OR char_length(object_ref) BETWEEN 1 AND 1024),
+  native_version_ref TEXT CONSTRAINT adcp_reporting_row_chunks_native_version_ref_bounds
+    CHECK (native_version_ref IS NULL OR char_length(native_version_ref) BETWEEN 1 AND 1024),
   compression TEXT NOT NULL DEFAULT 'none' CHECK (compression IN ('none', 'gzip')),
   physical_sha256 TEXT COLLATE "C" CHECK (physical_sha256 IS NULL OR physical_sha256 ~ '^[0-9a-f]{64}$'),
-  physical_byte_count BIGINT CHECK (physical_byte_count IS NULL OR physical_byte_count > 0),
+  size_bytes BIGINT CHECK (size_bytes IS NULL OR size_bytes > 0),
   PRIMARY KEY (row_set_id, chunk_index),
   FOREIGN KEY (row_set_id, account_id, obligation_id)
     REFERENCES adcp_reporting_row_sets (row_set_id, account_id, obligation_id),
-  CHECK ((object_key IS NULL) = (native_version IS NULL)),
-  CHECK ((object_key IS NULL) = (physical_sha256 IS NULL)),
-  CHECK ((object_key IS NULL) = (physical_byte_count IS NULL))
+  CHECK ((object_ref IS NULL) = (native_version_ref IS NULL)),
+  CHECK ((object_ref IS NULL) = (physical_sha256 IS NULL)),
+  CHECK ((object_ref IS NULL) = (size_bytes IS NULL))
 );
 CREATE INDEX IF NOT EXISTS adcp_reporting_row_chunks_object
-  ON adcp_reporting_row_chunks (object_key, native_version)
-  WHERE object_key IS NOT NULL;
+  ON adcp_reporting_row_chunks (object_ref, native_version_ref)
+  WHERE object_ref IS NOT NULL;
 CREATE INDEX IF NOT EXISTS adcp_reporting_row_chunks_body
   ON adcp_reporting_row_chunks (account_id, obligation_id, sha256)
-  WHERE object_key IS NULL;
+  WHERE object_ref IS NULL;
 
 CREATE TABLE IF NOT EXISTS adcp_reporting_chunk_bodies (
   account_id TEXT COLLATE "C" NOT NULL,
@@ -161,12 +211,12 @@ BEGIN
       RAISE EXCEPTION 'reporting row binding identity is immutable' USING ERRCODE = '23514';
     END IF;
   ELSIF TG_TABLE_NAME = 'adcp_reporting_row_sets' THEN
-    IF (NEW.row_set_id, NEW.row_set_kind, NEW.account_id, NEW.obligation_id, NEW.encoding, NEW.digest_profile,
-        NEW.content_sha256, NEW.canonical_byte_count, NEW.row_count, NEW.row_manifest_sha256, NEW.chunk_count,
+    IF (NEW.row_set_id, NEW.row_set_kind, NEW.account_id, NEW.obligation_id, NEW.format, NEW.algorithm,
+        NEW.digest_profile, NEW.content_sha256, NEW.content_size_bytes, NEW.row_count, NEW.row_manifest_sha256, NEW.chunk_count,
         NEW.rows_shared_from_row_set_id, NEW.recorded_at)
        IS DISTINCT FROM
-       (OLD.row_set_id, OLD.row_set_kind, OLD.account_id, OLD.obligation_id, OLD.encoding, OLD.digest_profile,
-        OLD.content_sha256, OLD.canonical_byte_count, OLD.row_count, OLD.row_manifest_sha256, OLD.chunk_count,
+       (OLD.row_set_id, OLD.row_set_kind, OLD.account_id, OLD.obligation_id, OLD.format, OLD.algorithm,
+        OLD.digest_profile, OLD.content_sha256, OLD.content_size_bytes, OLD.row_count, OLD.row_manifest_sha256, OLD.chunk_count,
         OLD.rows_shared_from_row_set_id, OLD.recorded_at) THEN
       RAISE EXCEPTION 'reporting row set content is immutable' USING ERRCODE = '23514';
     END IF;
@@ -176,10 +226,10 @@ BEGIN
     END IF;
   ELSIF TG_TABLE_NAME = 'adcp_reporting_row_chunks' THEN
     IF (NEW.row_set_id, NEW.chunk_index, NEW.account_id, NEW.obligation_id, NEW.first_ordinal, NEW.row_count,
-        NEW.byte_count, NEW.sha256, NEW.segments)
+        NEW.canonical_size_bytes, NEW.sha256, NEW.segments)
        IS DISTINCT FROM
        (OLD.row_set_id, OLD.chunk_index, OLD.account_id, OLD.obligation_id, OLD.first_ordinal, OLD.row_count,
-        OLD.byte_count, OLD.sha256, OLD.segments) THEN
+        OLD.canonical_size_bytes, OLD.sha256, OLD.segments) THEN
       RAISE EXCEPTION 'reporting row chunk content is immutable' USING ERRCODE = '23514';
     END IF;
   ELSIF TG_TABLE_NAME = 'adcp_reporting_chunk_bodies' THEN
@@ -213,6 +263,50 @@ BEGIN
   END LOOP;
 END
 $triggers$;
+
+-- AdCP bounds on installs created before they existed (a fresh install has them inline).
+DO $bounds$
+DECLARE
+  offending BIGINT;
+BEGIN
+  SELECT count(*) INTO offending FROM adcp_reporting_row_chunks
+   WHERE object_ref IS NOT NULL
+     AND (char_length(object_ref) NOT BETWEEN 1 AND 1024 OR char_length(native_version_ref) NOT BETWEEN 1 AND 1024);
+  IF offending > 0 THEN
+    RAISE EXCEPTION 'reporting row storage: % chunk(s) hold an object_ref or native_version_ref outside AdCP 1 to 1024 characters; re-sync them before applying this migration', offending
+      USING ERRCODE = '23514';
+  END IF;
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'adcp_reporting_row_chunks_object_ref_bounds'
+       AND conrelid = to_regclass(quote_ident(current_schema()) || '.adcp_reporting_row_chunks')
+  ) THEN
+    ALTER TABLE adcp_reporting_row_chunks ADD CONSTRAINT adcp_reporting_row_chunks_object_ref_bounds
+      CHECK (object_ref IS NULL OR char_length(object_ref) BETWEEN 1 AND 1024);
+  END IF;
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'adcp_reporting_row_chunks_native_version_ref_bounds'
+       AND conrelid = to_regclass(quote_ident(current_schema()) || '.adcp_reporting_row_chunks')
+  ) THEN
+    ALTER TABLE adcp_reporting_row_chunks ADD CONSTRAINT adcp_reporting_row_chunks_native_version_ref_bounds
+      CHECK (native_version_ref IS NULL OR char_length(native_version_ref) BETWEEN 1 AND 1024);
+  END IF;
+END
+$bounds$;
+
+-- Open write intents written before the rename name objects objectKey / nativeVersion.
+UPDATE adcp_reporting_row_write_intents
+   SET created_objects = (
+     SELECT COALESCE(jsonb_agg(
+       CASE WHEN jsonb_typeof(created) = 'object' AND created ? 'objectKey'
+         THEN jsonb_build_object('object_ref', created -> 'objectKey', 'native_version_ref', created -> 'nativeVersion')
+         ELSE created END
+       ORDER BY ordinality
+     ), '[]'::jsonb)
+       FROM jsonb_array_elements(created_objects) WITH ORDINALITY AS element(created, ordinality)
+   )
+ WHERE EXISTS (SELECT 1 FROM jsonb_array_elements(created_objects) AS element(created) WHERE jsonb_typeof(created) = 'object' AND created ? 'objectKey');
 `.trim();
 const REPORTING_ROW_STORAGE_TABLES = Object.freeze([
   "adcp_persistence_installation",
@@ -222,6 +316,15 @@ const REPORTING_ROW_STORAGE_TABLES = Object.freeze([
   "adcp_reporting_chunk_bodies",
   "adcp_reporting_row_write_intents"
 ]);
+const REPORTING_ROW_STORAGE_REQUIRED_COLUMNS = Object.freeze([
+  "adcp_reporting_row_sets.format",
+  "adcp_reporting_row_sets.algorithm",
+  "adcp_reporting_row_sets.content_size_bytes",
+  "adcp_reporting_row_chunks.canonical_size_bytes",
+  "adcp_reporting_row_chunks.object_ref",
+  "adcp_reporting_row_chunks.native_version_ref",
+  "adcp_reporting_row_chunks.size_bytes"
+]);
 async function probeReportingRowStorageSchemaV1(pool) {
   const present = await pool.query(
     `SELECT table_name AS name FROM information_schema.tables
@@ -235,6 +338,18 @@ async function probeReportingRowStorageSchemaV1(pool) {
       `Reporting row storage requires REPORTING_ROW_STORAGE_MIGRATION; missing tables: ${missing.join(", ")}`
     );
   }
+  const columns = await pool.query(
+    `SELECT table_name || '.' || column_name AS name FROM information_schema.columns
+      WHERE table_schema = current_schema() AND table_name = ANY($1::text[])`,
+    [["adcp_reporting_row_chunks", "adcp_reporting_row_sets"]]
+  );
+  const columnNames = new Set(columns.rows.map((row) => row.name));
+  const absent = REPORTING_ROW_STORAGE_REQUIRED_COLUMNS.filter((name) => !columnNames.has(name));
+  if (absent.length > 0) {
+    throw new Error(
+      `Reporting row storage requires the current REPORTING_ROW_STORAGE_MIGRATION; missing columns: ${absent.join(", ")}`
+    );
+  }
   const installation = await pool.query(
     "SELECT installation_id::text AS installation_id FROM adcp_persistence_installation WHERE singleton"
   );

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

@@ -1,4 +1,51 @@
 const REPORTING_ROW_STORAGE_MIGRATION = `
+-- Serialize concurrent appliers (several instances may run migrations at startup) so the guarded
+-- renames below cannot race each other. Released at the end of this implicit transaction.
+SELECT pg_advisory_xact_lock(hashtextextended('adcp-reporting-row-storage-migration', 0));
+
+-- In-place upgrade from the pre-AdCP-alignment column names. Every step is guarded, so a fresh
+-- install (no tables yet) and a reapplied migration are both no-ops here.
+DO $align$
+DECLARE
+  renames TEXT[][] := ARRAY[
+    ARRAY['adcp_reporting_row_chunks', 'object_key', 'object_ref'],
+    ARRAY['adcp_reporting_row_chunks', 'native_version', 'native_version_ref'],
+    ARRAY['adcp_reporting_row_chunks', 'byte_count', 'canonical_size_bytes'],
+    ARRAY['adcp_reporting_row_chunks', 'physical_byte_count', 'size_bytes'],
+    ARRAY['adcp_reporting_row_sets', 'canonical_byte_count', 'content_size_bytes']
+  ];
+  item TEXT[];
+BEGIN
+  FOREACH item SLICE 1 IN ARRAY renames LOOP
+    IF EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = current_schema() AND table_name = item[1] AND column_name = item[2]
+    ) AND NOT EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = current_schema() AND table_name = item[1] AND column_name = item[3]
+    ) THEN
+      EXECUTE format('ALTER TABLE %I RENAME COLUMN %I TO %I', item[1], item[2], item[3]);
+    END IF;
+  END LOOP;
+  -- encoding = 'adcp_canonical_jsonl_v1' becomes AdCP's format = 'jsonl' plus
+  -- algorithm = 'adcp_jcs_rows_v1'. The old CHECK admitted one value, so the defaults backfill
+  -- every row without an UPDATE (the immutability trigger forbids one).
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_schema = current_schema() AND table_name = 'adcp_reporting_row_sets' AND column_name = 'encoding'
+  ) AND NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_schema = current_schema() AND table_name = 'adcp_reporting_row_sets' AND column_name = 'format'
+  ) THEN
+    ALTER TABLE adcp_reporting_row_sets
+      ADD COLUMN format TEXT NOT NULL DEFAULT 'jsonl' CHECK (format = 'jsonl'),
+      ADD COLUMN algorithm TEXT NOT NULL DEFAULT 'adcp_jcs_rows_v1' CHECK (algorithm = 'adcp_jcs_rows_v1');
+    ALTER TABLE adcp_reporting_row_sets ALTER COLUMN format DROP DEFAULT, ALTER COLUMN algorithm DROP DEFAULT;
+    ALTER TABLE adcp_reporting_row_sets DROP COLUMN encoding;
+  END IF;
+END
+$align$;
+
 CREATE TABLE IF NOT EXISTS adcp_persistence_installation (
   singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),
   installation_id UUID NOT NULL DEFAULT gen_random_uuid(),
@@ -25,10 +72,11 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_row_sets (
   row_set_kind TEXT NOT NULL CHECK (row_set_kind IN ('revision', 'adjustment')),
   account_id TEXT COLLATE "C" NOT NULL,
   obligation_id TEXT COLLATE "C" NOT NULL REFERENCES adcp_reporting_obligations(obligation_id),
-  encoding TEXT NOT NULL CHECK (encoding = 'adcp_canonical_jsonl_v1'),
+  format TEXT NOT NULL CHECK (format = 'jsonl'),
+  algorithm TEXT NOT NULL CHECK (algorithm = 'adcp_jcs_rows_v1'),
   digest_profile TEXT NOT NULL CHECK (digest_profile IN ('revision_envelope_v1', 'rows_v1')),
   content_sha256 TEXT COLLATE "C" NOT NULL CHECK (content_sha256 ~ '^[0-9a-f]{64}$'),
-  canonical_byte_count BIGINT NOT NULL CHECK (canonical_byte_count > 0),
+  content_size_bytes BIGINT NOT NULL CHECK (content_size_bytes > 0),
   row_count BIGINT NOT NULL CHECK (row_count >= 0),
   row_manifest_sha256 TEXT COLLATE "C" NOT NULL CHECK (row_manifest_sha256 ~ '^[0-9a-f]{64}$'),
   chunk_count INTEGER NOT NULL CHECK (chunk_count >= 0),
@@ -62,27 +110,29 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_row_chunks (
   obligation_id TEXT COLLATE "C" NOT NULL,
   first_ordinal BIGINT NOT NULL CHECK (first_ordinal >= 0),
   row_count INTEGER NOT NULL CHECK (row_count > 0),
-  byte_count BIGINT NOT NULL CHECK (byte_count > 0),
+  canonical_size_bytes BIGINT NOT NULL CHECK (canonical_size_bytes > 0),
   sha256 TEXT COLLATE "C" NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'),
   segments JSONB NOT NULL CHECK (jsonb_typeof(segments) = 'array'),
-  object_key TEXT COLLATE "C",
-  native_version TEXT,
+  object_ref TEXT COLLATE "C" CONSTRAINT adcp_reporting_row_chunks_object_ref_bounds
+    CHECK (object_ref IS NULL OR char_length(object_ref) BETWEEN 1 AND 1024),
+  native_version_ref TEXT CONSTRAINT adcp_reporting_row_chunks_native_version_ref_bounds
+    CHECK (native_version_ref IS NULL OR char_length(native_version_ref) BETWEEN 1 AND 1024),
   compression TEXT NOT NULL DEFAULT 'none' CHECK (compression IN ('none', 'gzip')),
   physical_sha256 TEXT COLLATE "C" CHECK (physical_sha256 IS NULL OR physical_sha256 ~ '^[0-9a-f]{64}$'),
-  physical_byte_count BIGINT CHECK (physical_byte_count IS NULL OR physical_byte_count > 0),
+  size_bytes BIGINT CHECK (size_bytes IS NULL OR size_bytes > 0),
   PRIMARY KEY (row_set_id, chunk_index),
   FOREIGN KEY (row_set_id, account_id, obligation_id)
     REFERENCES adcp_reporting_row_sets (row_set_id, account_id, obligation_id),
-  CHECK ((object_key IS NULL) = (native_version IS NULL)),
-  CHECK ((object_key IS NULL) = (physical_sha256 IS NULL)),
-  CHECK ((object_key IS NULL) = (physical_byte_count IS NULL))
+  CHECK ((object_ref IS NULL) = (native_version_ref IS NULL)),
+  CHECK ((object_ref IS NULL) = (physical_sha256 IS NULL)),
+  CHECK ((object_ref IS NULL) = (size_bytes IS NULL))
 );
 CREATE INDEX IF NOT EXISTS adcp_reporting_row_chunks_object
-  ON adcp_reporting_row_chunks (object_key, native_version)
-  WHERE object_key IS NOT NULL;
+  ON adcp_reporting_row_chunks (object_ref, native_version_ref)
+  WHERE object_ref IS NOT NULL;
 CREATE INDEX IF NOT EXISTS adcp_reporting_row_chunks_body
   ON adcp_reporting_row_chunks (account_id, obligation_id, sha256)
-  WHERE object_key IS NULL;
+  WHERE object_ref IS NULL;
 
 CREATE TABLE IF NOT EXISTS adcp_reporting_chunk_bodies (
   account_id TEXT COLLATE "C" NOT NULL,
@@ -136,12 +186,12 @@ BEGIN
       RAISE EXCEPTION 'reporting row binding identity is immutable' USING ERRCODE = '23514';
     END IF;
   ELSIF TG_TABLE_NAME = 'adcp_reporting_row_sets' THEN
-    IF (NEW.row_set_id, NEW.row_set_kind, NEW.account_id, NEW.obligation_id, NEW.encoding, NEW.digest_profile,
-        NEW.content_sha256, NEW.canonical_byte_count, NEW.row_count, NEW.row_manifest_sha256, NEW.chunk_count,
+    IF (NEW.row_set_id, NEW.row_set_kind, NEW.account_id, NEW.obligation_id, NEW.format, NEW.algorithm,
+        NEW.digest_profile, NEW.content_sha256, NEW.content_size_bytes, NEW.row_count, NEW.row_manifest_sha256, NEW.chunk_count,
         NEW.rows_shared_from_row_set_id, NEW.recorded_at)
        IS DISTINCT FROM
-       (OLD.row_set_id, OLD.row_set_kind, OLD.account_id, OLD.obligation_id, OLD.encoding, OLD.digest_profile,
-        OLD.content_sha256, OLD.canonical_byte_count, OLD.row_count, OLD.row_manifest_sha256, OLD.chunk_count,
+       (OLD.row_set_id, OLD.row_set_kind, OLD.account_id, OLD.obligation_id, OLD.format, OLD.algorithm,
+        OLD.digest_profile, OLD.content_sha256, OLD.content_size_bytes, OLD.row_count, OLD.row_manifest_sha256, OLD.chunk_count,
         OLD.rows_shared_from_row_set_id, OLD.recorded_at) THEN
       RAISE EXCEPTION 'reporting row set content is immutable' USING ERRCODE = '23514';
     END IF;
@@ -151,10 +201,10 @@ BEGIN
     END IF;
   ELSIF TG_TABLE_NAME = 'adcp_reporting_row_chunks' THEN
     IF (NEW.row_set_id, NEW.chunk_index, NEW.account_id, NEW.obligation_id, NEW.first_ordinal, NEW.row_count,
-        NEW.byte_count, NEW.sha256, NEW.segments)
+        NEW.canonical_size_bytes, NEW.sha256, NEW.segments)
        IS DISTINCT FROM
        (OLD.row_set_id, OLD.chunk_index, OLD.account_id, OLD.obligation_id, OLD.first_ordinal, OLD.row_count,
-        OLD.byte_count, OLD.sha256, OLD.segments) THEN
+        OLD.canonical_size_bytes, OLD.sha256, OLD.segments) THEN
       RAISE EXCEPTION 'reporting row chunk content is immutable' USING ERRCODE = '23514';
     END IF;
   ELSIF TG_TABLE_NAME = 'adcp_reporting_chunk_bodies' THEN
@@ -188,6 +238,50 @@ BEGIN
   END LOOP;
 END
 $triggers$;
+
+-- AdCP bounds on installs created before they existed (a fresh install has them inline).
+DO $bounds$
+DECLARE
+  offending BIGINT;
+BEGIN
+  SELECT count(*) INTO offending FROM adcp_reporting_row_chunks
+   WHERE object_ref IS NOT NULL
+     AND (char_length(object_ref) NOT BETWEEN 1 AND 1024 OR char_length(native_version_ref) NOT BETWEEN 1 AND 1024);
+  IF offending > 0 THEN
+    RAISE EXCEPTION 'reporting row storage: % chunk(s) hold an object_ref or native_version_ref outside AdCP 1 to 1024 characters; re-sync them before applying this migration', offending
+      USING ERRCODE = '23514';
+  END IF;
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'adcp_reporting_row_chunks_object_ref_bounds'
+       AND conrelid = to_regclass(quote_ident(current_schema()) || '.adcp_reporting_row_chunks')
+  ) THEN
+    ALTER TABLE adcp_reporting_row_chunks ADD CONSTRAINT adcp_reporting_row_chunks_object_ref_bounds
+      CHECK (object_ref IS NULL OR char_length(object_ref) BETWEEN 1 AND 1024);
+  END IF;
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'adcp_reporting_row_chunks_native_version_ref_bounds'
+       AND conrelid = to_regclass(quote_ident(current_schema()) || '.adcp_reporting_row_chunks')
+  ) THEN
+    ALTER TABLE adcp_reporting_row_chunks ADD CONSTRAINT adcp_reporting_row_chunks_native_version_ref_bounds
+      CHECK (native_version_ref IS NULL OR char_length(native_version_ref) BETWEEN 1 AND 1024);
+  END IF;
+END
+$bounds$;
+
+-- Open write intents written before the rename name objects objectKey / nativeVersion.
+UPDATE adcp_reporting_row_write_intents
+   SET created_objects = (
+     SELECT COALESCE(jsonb_agg(
+       CASE WHEN jsonb_typeof(created) = 'object' AND created ? 'objectKey'
+         THEN jsonb_build_object('object_ref', created -> 'objectKey', 'native_version_ref', created -> 'nativeVersion')
+         ELSE created END
+       ORDER BY ordinality
+     ), '[]'::jsonb)
+       FROM jsonb_array_elements(created_objects) WITH ORDINALITY AS element(created, ordinality)
+   )
+ WHERE EXISTS (SELECT 1 FROM jsonb_array_elements(created_objects) AS element(created) WHERE jsonb_typeof(created) = 'object' AND created ? 'objectKey');
 `.trim();
 const REPORTING_ROW_STORAGE_TABLES = Object.freeze([
   "adcp_persistence_installation",
@@ -197,6 +291,15 @@ const REPORTING_ROW_STORAGE_TABLES = Object.freeze([
   "adcp_reporting_chunk_bodies",
   "adcp_reporting_row_write_intents"
 ]);
+const REPORTING_ROW_STORAGE_REQUIRED_COLUMNS = Object.freeze([
+  "adcp_reporting_row_sets.format",
+  "adcp_reporting_row_sets.algorithm",
+  "adcp_reporting_row_sets.content_size_bytes",
+  "adcp_reporting_row_chunks.canonical_size_bytes",
+  "adcp_reporting_row_chunks.object_ref",
+  "adcp_reporting_row_chunks.native_version_ref",
+  "adcp_reporting_row_chunks.size_bytes"
+]);
 async function probeReportingRowStorageSchemaV1(pool) {
   const present = await pool.query(
     `SELECT table_name AS name FROM information_schema.tables
@@ -210,6 +313,18 @@ async function probeReportingRowStorageSchemaV1(pool) {
       `Reporting row storage requires REPORTING_ROW_STORAGE_MIGRATION; missing tables: ${missing.join(", ")}`
     );
   }
+  const columns = await pool.query(
+    `SELECT table_name || '.' || column_name AS name FROM information_schema.columns
+      WHERE table_schema = current_schema() AND table_name = ANY($1::text[])`,
+    [["adcp_reporting_row_chunks", "adcp_reporting_row_sets"]]
+  );
+  const columnNames = new Set(columns.rows.map((row) => row.name));
+  const absent = REPORTING_ROW_STORAGE_REQUIRED_COLUMNS.filter((name) => !columnNames.has(name));
+  if (absent.length > 0) {
+    throw new Error(
+      `Reporting row storage requires the current REPORTING_ROW_STORAGE_MIGRATION; missing columns: ${absent.join(", ")}`
+    );
+  }
   const installation = await pool.query(
     "SELECT installation_id::text AS installation_id FROM adcp_persistence_installation WHERE singleton"
   );

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

@@ -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;