@adcp/sdk 15.8.1 → 16.0.0-beta.1

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

@@ -3,7 +3,8 @@ import { gunzipSync, gzipSync } from "zlib";
 import { canonicalize } from "../../utils/jcs.mjs";
 import {
   REPORTING_ROW_CHUNK_MAX_BYTES,
-  REPORTING_ROW_ENCODING_V1,
+  REPORTING_ROW_ALGORITHM_V1,
+  REPORTING_ROW_FORMAT_V1,
   createReportingRevisionEnvelopeHasherV1,
   createReportingRowsOnlyHasherV1,
   decodeVerifiedReportingRowSegmentsV1,
@@ -16,6 +17,7 @@ import { probeReportingRowStorageSchemaV1 } from "./row-storage-migration.mjs";
 import { ReportingRowStoreError, isReportingRowStoreError } from "./row-storage-errors.mjs";
 import {
   REPORTING_ROW_DEFAULT_KEY_TEMPLATE,
+  REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH,
   assertReportingRowKeyTemplateV1,
   assertReportingRowPrefixV1,
   renderReportingRowObjectKeyV1
@@ -44,12 +46,14 @@ class ReportingRowStorageV1 {
       if (!provider) throw new ReportingRowStoreError("INVALID_INPUT", `row binding ${id} names an unknown provider`);
       provider.validateLocation(binding.location);
       assertReportingRowPrefixV1(binding.prefix);
-      assertReportingRowKeyTemplateV1(binding.keyTemplate ?? REPORTING_ROW_DEFAULT_KEY_TEMPLATE);
       if (binding.credentialRef !== void 0 && !CREDENTIAL_REF.test(binding.credentialRef)) {
         throw new ReportingRowStoreError("INVALID_INPUT", `row binding ${id} has an invalid credentialRef`);
       }
     }
-    this.bindings = Object.freeze({ ...bindings });
+    this.bindings = Object.freeze(
+      Object.fromEntries(Object.entries(bindings).map(([id, binding]) => [id, Object.freeze({ ...binding })]))
+    );
+    this.assertBindingKeyTemplates();
     this.deploymentNamespace = options.deploymentNamespace ?? "default";
     if (!this.deploymentNamespace || this.deploymentNamespace.length > 256) {
       throw new ReportingRowStoreError("INVALID_INPUT", "deploymentNamespace must be 1-256 characters");
@@ -70,12 +74,34 @@ class ReportingRowStorageV1 {
   get writeDeadlineMilliseconds() {
     return this.writeDeadline;
   }
+  /** Every writable object binding's key template must include `{revision_key}`; throws `INVALID_INPUT`. */
+  assertBindingKeyTemplates() {
+    for (const [id, binding] of Object.entries(this.bindings)) {
+      if (binding.kind !== "object") continue;
+      try {
+        assertReportingRowKeyTemplateV1(binding.keyTemplate ?? REPORTING_ROW_DEFAULT_KEY_TEMPLATE, {
+          requireRevisionKey: binding.readOnly !== true
+        });
+      } catch (error) {
+        if (isReportingRowStoreError(error)) {
+          throw new ReportingRowStoreError(
+            "INVALID_INPUT",
+            `row binding ${id}: ${error.message.replace(/^Reporting row store: INVALID_INPUT: /, "")}`
+          );
+        }
+        throw error;
+      }
+    }
+  }
   /**
    * 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
@@ -83,7 +109,7 @@ class ReportingRowStorageV1 {
    */
   assertCompactionSafeKeyTemplates() {
     const unsafe = Object.entries(this.bindings).filter(
-      ([, binding]) => binding.kind === "object" && !(binding.keyTemplate ?? REPORTING_ROW_DEFAULT_KEY_TEMPLATE).includes("{revision_key}")
+      ([, binding]) => binding.kind === "object" && binding.readOnly !== true && !(binding.keyTemplate ?? REPORTING_ROW_DEFAULT_KEY_TEMPLATE).includes("{revision_key}")
     ).map(([id]) => id);
     if (unsafe.length > 0) {
       throw new ReportingRowStoreError(
@@ -92,6 +118,10 @@ class ReportingRowStorageV1 {
       );
     }
   }
+  /** IDs of the object bindings this host configures, the only ones it can delete objects through. */
+  objectBindingIds() {
+    return Object.entries(this.bindings).filter(([, binding]) => binding.kind === "object").map(([id]) => id);
+  }
   /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
   ready() {
     this.readied ??= this.register().catch((error) => {
@@ -121,30 +151,46 @@ class ReportingRowStorageV1 {
     if (digest.sha256 !== input.binding.sha256 || digest.byteCount !== input.binding.byteCount || input.binding.rowCount !== input.rows.length) {
       throw new ReportingRowStoreError("INVALID_INPUT", "rows do not reproduce their committed binding");
     }
-    const ids = Object.keys(this.bindings);
+    const writable = Object.keys(this.bindings).filter((id) => {
+      const candidate = this.bindings[id];
+      return candidate.kind !== "object" || candidate.readOnly !== true;
+    });
+    if (writable.length === 0 && !input.bindingId && !this.options.selectRowBinding) {
+      throw new ReportingRowStoreError(
+        "UNSAFE_BINDING",
+        "no writable row binding is configured: every binding is readOnly"
+      );
+    }
     const bindingId = input.bindingId ? input.bindingId : this.options.selectRowBinding ? await this.options.selectRowBinding({
       account_id: input.accountId,
       reporting_obligation_id: input.obligationId,
       row_set_kind: input.rowSetKind,
       ...input.finality ? { finality: input.finality } : {},
       row_count: input.rows.length,
-      canonical_byte_count: digest.byteCount
-    }) : ids.length === 1 ? ids[0] : DEFAULT_BINDING_ID;
+      content_size_bytes: digest.byteCount
+    }) : writable.length === 1 ? writable[0] : DEFAULT_BINDING_ID;
     const binding = this.bindings[bindingId];
     if (!binding) throw new ReportingRowStoreError("STATE_UNAVAILABLE", `row binding ${bindingId} is not configured`);
+    if (binding.kind === "object" && binding.readOnly === true) {
+      throw new ReportingRowStoreError(
+        "UNSAFE_BINDING",
+        `row binding ${bindingId} is read-only and cannot take new row sets`
+      );
+    }
     if (binding.kind === "postgres") return Object.freeze({ input, encoded, bindingId, binding, digestProfile });
     const compression = binding.compression ?? "gzip";
     const namespaceKey = this.installation.namespaceKey;
     const objects = encoded.chunks.map((chunk) => {
       const physicalBytes = compression === "gzip" ? gzipSync(chunk.bytes, { level: 6 }) : chunk.bytes;
       return Object.freeze({
-        key: renderReportingRowObjectKeyV1({
+        objectRef: renderReportingRowObjectKeyV1({
           template: binding.keyTemplate ?? REPORTING_ROW_DEFAULT_KEY_TEMPLATE,
           prefix: binding.prefix,
           namespaceKey,
           accountId: input.accountId,
           rowSetId: input.rowSetId,
           ...input.periodStart ? { periodStart: input.periodStart } : {},
+          ...input.sourceTimezone ? { sourceTimezone: input.sourceTimezone } : {},
           ...input.finality ? { finality: input.finality } : {},
           contentSha256: input.binding.sha256,
           chunkIndex: chunk.manifest.chunk_index,
@@ -179,7 +225,7 @@ class ReportingRowStorageV1 {
         () => provider.putIfAbsent(
           {
             ...location,
-            key: object.key,
+            objectRef: object.objectRef,
             bytes: object.physicalBytes,
             contentType: object.compression === "gzip" ? "application/gzip" : "application/x-ndjson",
             metadata: {
@@ -191,20 +237,27 @@ class ReportingRowStorageV1 {
         )
       );
       if (put.created) {
-        await onCreated({ objectKey: object.key, nativeVersion: put.nativeVersion });
+        await onCreated({ objectRef: object.objectRef, nativeVersionRef: put.nativeVersionRef });
+        assertNativeVersionRef(put.nativeVersionRef);
         locators.push({
-          objectKey: object.key,
-          nativeVersion: put.nativeVersion,
+          objectRef: object.objectRef,
+          nativeVersionRef: put.nativeVersionRef,
           compression: object.compression,
           physicalSha256: object.physicalSha256,
-          physicalByteCount: object.physicalBytes.byteLength,
+          sizeBytes: object.physicalBytes.byteLength,
           created: true
         });
         continue;
       }
+      assertNativeVersionRef(put.nativeVersionRef);
       const existing = await this.provider(
         () => provider.get(
-          { ...location, key: object.key, nativeVersion: put.nativeVersion, maxBytes: MAX_ADOPTED_OBJECT_BYTES },
+          {
+            ...location,
+            objectRef: object.objectRef,
+            nativeVersionRef: put.nativeVersionRef,
+            maxBytes: MAX_ADOPTED_OBJECT_BYTES
+          },
           context
         )
       );
@@ -213,11 +266,11 @@ class ReportingRowStorageV1 {
         throw new ReportingRowStoreError("CONTENT_CONFLICT", `object for chunk ${index} holds different bytes`);
       }
       locators.push({
-        objectKey: object.key,
-        nativeVersion: put.nativeVersion,
+        objectRef: object.objectRef,
+        nativeVersionRef: put.nativeVersionRef,
         compression: object.compression,
         physicalSha256: sha256Hex(existing),
-        physicalByteCount: existing.byteLength,
+        sizeBytes: existing.byteLength,
         created: false
       });
     }
@@ -236,17 +289,18 @@ class ReportingRowStorageV1 {
     }
     const inserted = await transaction.query(
       `INSERT INTO adcp_reporting_row_sets
-         (row_set_id, row_set_kind, account_id, obligation_id, encoding, digest_profile, content_sha256,
-          canonical_byte_count, row_count, row_manifest_sha256, chunk_count, row_binding_id,
+         (row_set_id, row_set_kind, account_id, obligation_id, format, algorithm, digest_profile, content_sha256,
+          content_size_bytes, row_count, row_manifest_sha256, chunk_count, row_binding_id,
           rows_shared_from_row_set_id)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)
        ON CONFLICT (row_set_id) DO NOTHING`,
       [
         input.rowSetId,
         input.rowSetKind,
         input.accountId,
         input.obligationId,
-        REPORTING_ROW_ENCODING_V1,
+        REPORTING_ROW_FORMAT_V1,
+        REPORTING_ROW_ALGORITHM_V1,
         prepared.digestProfile,
         input.binding.sha256,
         input.binding.byteCount,
@@ -280,8 +334,8 @@ class ReportingRowStorageV1 {
       }
       await transaction.query(
         `INSERT INTO adcp_reporting_row_chunks
-           (row_set_id, chunk_index, account_id, obligation_id, first_ordinal, row_count, byte_count, sha256, segments,
-            object_key, native_version, compression, physical_sha256, physical_byte_count)
+           (row_set_id, chunk_index, account_id, obligation_id, first_ordinal, row_count, canonical_size_bytes, sha256,
+            segments, object_ref, native_version_ref, compression, physical_sha256, size_bytes)
          VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11, $12, $13, $14)`,
         [
           input.rowSetId,
@@ -293,11 +347,11 @@ class ReportingRowStorageV1 {
           manifest.byte_count,
           manifest.sha256,
           JSON.stringify(manifest.segments),
-          locator?.objectKey ?? null,
-          locator?.nativeVersion ?? null,
+          locator?.objectRef ?? null,
+          locator?.nativeVersionRef ?? null,
           locator?.compression ?? "none",
           locator?.physicalSha256 ?? null,
-          locator?.physicalByteCount ?? null
+          locator?.sizeBytes ?? null
         ]
       );
     }
@@ -311,7 +365,7 @@ class ReportingRowStorageV1 {
   async find(rowSetId, accountId, queryable = this.pool) {
     const found = await queryable.query(
       `SELECT row_set.row_set_id, row_set.row_set_kind, row_set.account_id, row_set.obligation_id,
-              row_set.digest_profile, row_set.content_sha256, row_set.canonical_byte_count, row_set.row_count,
+              row_set.digest_profile, row_set.content_sha256, row_set.content_size_bytes, row_set.row_count,
               row_set.row_manifest_sha256, row_set.chunk_count, row_set.row_binding_id,
               row_set.row_location_version, row_set.rows_state, binding.kind, binding.identity_sha256
          FROM adcp_reporting_row_sets row_set
@@ -326,8 +380,8 @@ class ReportingRowStorageV1 {
     }
     if (record.rows_state === "unavailable") throw new ReportingRowStoreError("ROWS_UNAVAILABLE");
     const chunks = await queryable.query(
-      `SELECT chunk_index, first_ordinal, row_count, byte_count, sha256, segments,
-              object_key, native_version, compression, physical_sha256, physical_byte_count
+      `SELECT chunk_index, first_ordinal, row_count, canonical_size_bytes, sha256, segments,
+              object_ref, native_version_ref, compression, physical_sha256, size_bytes
          FROM adcp_reporting_row_chunks WHERE row_set_id = $1 ORDER BY chunk_index`,
       [rowSetId]
     );
@@ -335,7 +389,7 @@ class ReportingRowStorageV1 {
       chunk_index: chunk.chunk_index,
       first_ordinal: Number(chunk.first_ordinal),
       row_count: chunk.row_count,
-      byte_count: Number(chunk.byte_count),
+      byte_count: Number(chunk.canonical_size_bytes),
       sha256: chunk.sha256,
       segments: chunk.segments.map((segment) => ({
         first_ordinal: Number(segment.first_ordinal),
@@ -356,16 +410,16 @@ class ReportingRowStorageV1 {
       throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "chunk count does not match the row set");
     }
     const locators = chunks.rows.map((chunk) => {
-      const hasLocation = chunk.object_key !== null;
+      const hasLocation = chunk.object_ref !== null;
       if (hasLocation !== (record.kind === "object")) {
         throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "chunk location does not match its binding kind");
       }
       return hasLocation ? Object.freeze({
-        objectKey: chunk.object_key,
-        nativeVersion: chunk.native_version,
+        objectRef: chunk.object_ref,
+        nativeVersionRef: chunk.native_version_ref,
         compression: chunk.compression,
         physicalSha256: chunk.physical_sha256,
-        physicalByteCount: Number(chunk.physical_byte_count)
+        sizeBytes: Number(chunk.size_bytes)
       }) : void 0;
     });
     return Object.freeze({
@@ -375,7 +429,7 @@ class ReportingRowStorageV1 {
       obligationId: record.obligation_id,
       digestProfile: record.digest_profile,
       contentSha256: record.content_sha256,
-      canonicalByteCount: Number(record.canonical_byte_count),
+      contentSizeBytes: Number(record.content_size_bytes),
       rowCount,
       rowManifestSha256: record.row_manifest_sha256,
       bindingId: record.row_binding_id,
@@ -423,7 +477,7 @@ class ReportingRowStorageV1 {
    * `controlTotals` are required for revision row sets.
    */
   async readAll(handle, controlTotals, options = {}) {
-    if (options.maxBytes !== void 0 && handle.canonicalByteCount > options.maxBytes) {
+    if (options.maxBytes !== void 0 && handle.contentSizeBytes > options.maxBytes) {
       throw new ReportingRowStoreError("INVALID_INPUT", "row set exceeds the hydration byte limit");
     }
     const hasher = handle.digestProfile === "revision_envelope_v1" ? createReportingRevisionEnvelopeHasherV1({
@@ -442,7 +496,7 @@ class ReportingRowStorageV1 {
       );
     }
     const digest = this.decode(() => hasher.digest());
-    if (digest.sha256 !== handle.contentSha256 || digest.byteCount !== handle.canonicalByteCount) {
+    if (digest.sha256 !== handle.contentSha256 || digest.byteCount !== handle.contentSizeBytes) {
       throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "rows do not reproduce the committed binding");
     }
     return rows;
@@ -461,22 +515,28 @@ class ReportingRowStorageV1 {
     const ownedPrefix = `${binding.prefix}/${this.installation.namespaceKey}/`;
     const context = { signal: deadlineSignal(this.writeDeadline, signal) };
     for (const object of objects) {
-      if (!object.objectKey.startsWith(ownedPrefix)) {
+      if (!object.objectRef.startsWith(ownedPrefix)) {
         throw new ReportingRowStoreError("UNSAFE_BINDING", "refusing to delete an object outside the owned prefix");
       }
       await this.provider(
         () => provider.delete(
-          { ...providerLocation(binding), key: object.objectKey, nativeVersion: object.nativeVersion },
+          { ...providerLocation(binding), objectRef: object.objectRef, nativeVersionRef: object.nativeVersionRef },
           context
         )
       );
     }
   }
   /**
-   * 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.
    */
   async assertObjectsPresent(bindingId, objects, signal) {
     await this.ready();
@@ -486,24 +546,24 @@ class ReportingRowStorageV1 {
     }
     const provider = this.providers[binding.provider];
     const context = { signal: deadlineSignal(this.writeDeadline, signal) };
+    const location = providerLocation(binding);
+    const changed = () => new ReportingRowStoreError(
+      "STATE_UNAVAILABLE",
+      "an adopted row object was deleted or replaced before its commit; retry the upload"
+    );
     for (const object of objects) {
+      const identity = { ...location, objectRef: object.objectRef, nativeVersionRef: object.nativeVersionRef };
+      if (provider.stat) {
+        const stat = await this.provider(() => provider.stat(identity, context));
+        if (!stat || stat.nativeVersionRef !== object.nativeVersionRef || !Number.isSafeInteger(stat.sizeBytes) || stat.sizeBytes !== object.sizeBytes) {
+          throw changed();
+        }
+        continue;
+      }
       const bytes = await this.provider(
-        () => provider.get(
-          {
-            ...providerLocation(binding),
-            key: object.objectKey,
-            nativeVersion: object.nativeVersion,
-            maxBytes: MAX_ADOPTED_OBJECT_BYTES
-          },
-          context
-        )
+        () => provider.get({ ...identity, maxBytes: MAX_ADOPTED_OBJECT_BYTES }, context)
       );
-      if (!bytes || sha256Hex(bytes) !== object.physicalSha256) {
-        throw new ReportingRowStoreError(
-          "STATE_UNAVAILABLE",
-          "an adopted row object was deleted or replaced before its commit; retry the upload"
-        );
-      }
+      if (!bytes || sha256Hex(bytes) !== object.physicalSha256) throw changed();
     }
   }
   /**
@@ -530,21 +590,21 @@ class ReportingRowStorageV1 {
     const rowSetId = found.rows[0]?.row_set_id;
     if (!rowSetId) return void 0;
     const chunks = await queryable.query(
-      `SELECT object_key, native_version, compression, physical_sha256, physical_byte_count
+      `SELECT object_ref, native_version_ref, compression, physical_sha256, size_bytes
          FROM adcp_reporting_row_chunks WHERE row_set_id = $1 ORDER BY chunk_index`,
       [rowSetId]
     );
     if (chunks.rows.length !== prepared.encoded.chunks.length) return void 0;
     if (prepared.binding.kind === "postgres") return { rowSetId, locators: [] };
-    if (chunks.rows.some((chunk) => chunk.object_key === null)) return void 0;
+    if (chunks.rows.some((chunk) => chunk.object_ref === null)) return void 0;
     return {
       rowSetId,
       locators: chunks.rows.map((chunk) => ({
-        objectKey: chunk.object_key,
-        nativeVersion: chunk.native_version,
+        objectRef: chunk.object_ref,
+        nativeVersionRef: chunk.native_version_ref,
         compression: chunk.compression,
         physicalSha256: chunk.physical_sha256,
-        physicalByteCount: Number(chunk.physical_byte_count),
+        sizeBytes: Number(chunk.size_bytes),
         created: false
       }))
     };
@@ -579,8 +639,8 @@ class ReportingRowStorageV1 {
         () => provider.get(
           {
             ...location,
-            key: locator.objectKey,
-            nativeVersion: locator.nativeVersion,
+            objectRef: locator.objectRef,
+            nativeVersionRef: locator.nativeVersionRef,
             range: { offset: byteOffset, length: byteCount },
             maxBytes: byteCount
           },
@@ -598,9 +658,9 @@ class ReportingRowStorageV1 {
       () => provider.get(
         {
           ...location,
-          key: locator.objectKey,
-          nativeVersion: locator.nativeVersion,
-          maxBytes: locator.physicalByteCount
+          objectRef: locator.objectRef,
+          nativeVersionRef: locator.nativeVersionRef,
+          maxBytes: locator.sizeBytes
         },
         context
       )
@@ -608,7 +668,7 @@ class ReportingRowStorageV1 {
     if (!stored)
       throw new ReportingRowStoreError("ROWS_UNAVAILABLE", `chunk ${manifest.chunk_index} object is missing`);
     const physical = Buffer.from(stored);
-    if (physical.byteLength !== locator.physicalByteCount || sha256Hex(physical) !== locator.physicalSha256) {
+    if (physical.byteLength !== locator.sizeBytes || sha256Hex(physical) !== locator.physicalSha256) {
       throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", `chunk ${manifest.chunk_index} stored bytes differ`);
     }
     const logical = this.inflate(physical, locator.compression, manifest.byte_count);
@@ -647,6 +707,7 @@ class ReportingRowStorageV1 {
     }
   }
   async register() {
+    this.assertBindingKeyTemplates();
     const { installationId } = await probeReportingRowStorageSchemaV1(this.pool);
     const namespaceKey = sha256Hex(canonicalize(["adcp.rows.v1", this.deploymentNamespace, installationId]));
     this.installation = { installationId, namespaceKey };
@@ -716,6 +777,11 @@ function deadlineSignal(milliseconds, signal) {
   const timeout = AbortSignal.timeout(milliseconds);
   return signal ? AbortSignal.any([signal, timeout]) : timeout;
 }
+function assertNativeVersionRef(value) {
+  if (typeof value !== "string" || value.length < 1 || value.length > REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH) {
+    throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "provider returned an invalid native version reference");
+  }
+}
 function positiveMilliseconds(value, name) {
   if (!Number.isSafeInteger(value) || value < 1e3 || value > 6e5) {
     throw new ReportingRowStoreError("INVALID_INPUT", `${name} must be between 1000 and 600000`);

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

@@ -13,6 +13,19 @@ interface PeriodSchedule {
 }
 /** Only this explicit identity opts into civil days. Numeric schedules stay numeric. */
 export declare function isReportingCalendarDay(schedule: Schedule, sourceTimezone: string): boolean;
+/**
+ * The calendar date, as AdCP's `YYYY-MM-DD`, of a reporting period's start in the
+ * period's `source_timezone`. A period starting 2026-10-02T07:00:00Z in
+ * `America/Los_Angeles` begins on 2026-10-02 local time, while the same instant
+ * in `Asia/Tokyo` is 2026-10-02 and 2026-10-01T16:00:00Z is already 2026-10-02
+ * there. The date is the civil date of the start instant: a period that starts
+ * on a daylight-saving boundary keeps the local date it begins on.
+ *
+ * Fails closed: an unparseable instant, a missing, non-IANA or unknown
+ * timezone, or a year outside 0001-9999 throws instead of falling back to UTC.
+ * The runtime's own default zone is never consulted.
+ */
+export declare function reportingPeriodDate(periodStart: string, sourceTimezone: string): string;
 export declare function reportingCalendarDayRules(timeZone: string): ReportingCalendarRulesV1;
 export declare function isFrozenCalendarRulesMismatch(error: unknown): boolean;
 /** Prove a sealed ownership range using only facts resolved under its frozen rules. */

package/dist/lib/reporting/ledger/schedule.d.ts

@@ -13,6 +13,19 @@ interface PeriodSchedule {
 }
 /** Only this explicit identity opts into civil days. Numeric schedules stay numeric. */
 export declare function isReportingCalendarDay(schedule: Schedule, sourceTimezone: string): boolean;
+/**
+ * The calendar date, as AdCP's `YYYY-MM-DD`, of a reporting period's start in the
+ * period's `source_timezone`. A period starting 2026-10-02T07:00:00Z in
+ * `America/Los_Angeles` begins on 2026-10-02 local time, while the same instant
+ * in `Asia/Tokyo` is 2026-10-02 and 2026-10-01T16:00:00Z is already 2026-10-02
+ * there. The date is the civil date of the start instant: a period that starts
+ * on a daylight-saving boundary keeps the local date it begins on.
+ *
+ * Fails closed: an unparseable instant, a missing, non-IANA or unknown
+ * timezone, or a year outside 0001-9999 throws instead of falling back to UTC.
+ * The runtime's own default zone is never consulted.
+ */
+export declare function reportingPeriodDate(periodStart: string, sourceTimezone: string): string;
 export declare function reportingCalendarDayRules(timeZone: string): ReportingCalendarRulesV1;
 export declare function isFrozenCalendarRulesMismatch(error: unknown): boolean;
 /** Prove a sealed ownership range using only facts resolved under its frozen rules. */

package/dist/lib/reporting/ledger/schedule.js

@@ -28,12 +28,14 @@ __export(schedule_exports, {
   reportingCalendarDayOrigin: () => reportingCalendarDayOrigin,
   reportingCalendarDayRules: () => reportingCalendarDayRules,
   reportingCalendarDaySchedule: () => reportingCalendarDaySchedule,
+  reportingPeriodDate: () => reportingPeriodDate,
   reportingPeriodSchedule: () => reportingPeriodSchedule
 });
 module.exports = __toCommonJS(schedule_exports);
 var import_node_crypto = require("node:crypto");
 var import_jcs = require('../../utils/jcs.js');
 var import_source = require('../source/index.js');
+var import_instant = require('./instant.js');
 const DAY = 864e5;
 const HORIZON = 400 * DAY;
 function isReportingCalendarDay(schedule, sourceTimezone) {
@@ -69,6 +71,27 @@ function formatterFor(timeZone) {
   formatters.set(canonical, candidate);
   return candidate;
 }
+function reportingPeriodDate(periodStart, sourceTimezone) {
+  if (typeof periodStart !== "string") throw new TypeError("Reporting period start must be an RFC 3339 instant");
+  if (typeof sourceTimezone !== "string" || sourceTimezone.length === 0 || sourceTimezone.length > 255) {
+    throw new TypeError("Reporting period date requires the period source_timezone");
+  }
+  const literal = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):/.exec(periodStart);
+  if (!literal || Number(literal[2]) < 1 || Number(literal[2]) > 12 || Number(literal[3]) < 1 || Number(literal[3]) > new Date(Date.UTC(2e3 + Number(literal[1]) % 400, Number(literal[2]), 0)).getUTCDate() || Number(literal[4]) > 23) {
+    throw new TypeError("Reporting period start must be an RFC 3339 instant");
+  }
+  const instant = Date.parse((0, import_instant.canonicalReportingInstant)(periodStart));
+  if (!Number.isFinite(instant)) throw new TypeError("Reporting period start must be an RFC 3339 instant");
+  const parts = formatterFor(sourceTimezone).formatToParts(instant);
+  const field = (type) => parts.find((part) => part.type === type)?.value;
+  const year = field("year");
+  const month = field("month");
+  const day = field("day");
+  if (field("era") !== "AD" || !year || !month || !day || !/^\d{1,4}$/.test(year) || !/^\d+$/.test(month + day)) {
+    throw new RangeError("Reporting period date is outside the supported civil year range");
+  }
+  return `${year.padStart(4, "0")}-${month}-${day}`;
+}
 function reportingCalendarDayRules(timeZone) {
   const formatter = formatterFor(timeZone);
   const tzdbVersion = process.versions.tz;
@@ -301,5 +324,6 @@ function assertReportingCalendarDayPeriod(schedule, sourceTimezone, source, star
   reportingCalendarDayOrigin,
   reportingCalendarDayRules,
   reportingCalendarDaySchedule,
+  reportingPeriodDate,
   reportingPeriodSchedule
 });

package/dist/lib/reporting/ledger/schedule.mjs

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { canonicalize } from "../../utils/jcs.mjs";
 import { reportingIsoDurationMillisecondsV1 } from "../source/index.mjs";
+import { canonicalReportingInstant } from "./instant.mjs";
 const DAY = 864e5;
 const HORIZON = 400 * DAY;
 function isReportingCalendarDay(schedule, sourceTimezone) {
@@ -36,6 +37,27 @@ function formatterFor(timeZone) {
   formatters.set(canonical, candidate);
   return candidate;
 }
+function reportingPeriodDate(periodStart, sourceTimezone) {
+  if (typeof periodStart !== "string") throw new TypeError("Reporting period start must be an RFC 3339 instant");
+  if (typeof sourceTimezone !== "string" || sourceTimezone.length === 0 || sourceTimezone.length > 255) {
+    throw new TypeError("Reporting period date requires the period source_timezone");
+  }
+  const literal = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):/.exec(periodStart);
+  if (!literal || Number(literal[2]) < 1 || Number(literal[2]) > 12 || Number(literal[3]) < 1 || Number(literal[3]) > new Date(Date.UTC(2e3 + Number(literal[1]) % 400, Number(literal[2]), 0)).getUTCDate() || Number(literal[4]) > 23) {
+    throw new TypeError("Reporting period start must be an RFC 3339 instant");
+  }
+  const instant = Date.parse(canonicalReportingInstant(periodStart));
+  if (!Number.isFinite(instant)) throw new TypeError("Reporting period start must be an RFC 3339 instant");
+  const parts = formatterFor(sourceTimezone).formatToParts(instant);
+  const field = (type) => parts.find((part) => part.type === type)?.value;
+  const year = field("year");
+  const month = field("month");
+  const day = field("day");
+  if (field("era") !== "AD" || !year || !month || !day || !/^\d{1,4}$/.test(year) || !/^\d+$/.test(month + day)) {
+    throw new RangeError("Reporting period date is outside the supported civil year range");
+  }
+  return `${year.padStart(4, "0")}-${month}-${day}`;
+}
 function reportingCalendarDayRules(timeZone) {
   const formatter = formatterFor(timeZone);
   const tzdbVersion = process.versions.tz;
@@ -267,5 +289,6 @@ export {
   reportingCalendarDayOrigin,
   reportingCalendarDayRules,
   reportingCalendarDaySchedule,
+  reportingPeriodDate,
   reportingPeriodSchedule
 };